Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

You must have previously installed the SonarQube Runner and read Analyzing Code Source. You must also have the language plugins installed for each of the languages you wish analyzed in your projects. 

Usage

Simple Project

Create a configuration file in the root directory of the project: sonar-project.properties

Code Block
titlesonar-project.properties
languagebash
# requiredRequired metadata
sonar.projectKey=my:project
sonar.projectName=My project
sonar.projectVersion=1.0

# optionalPath description
sonar.projectDescription=Fake description

# path to source directories (required)
sonar.sources=srcDir1,srcDir2

# The value of the property must be the key of the language.
sonar.language=cobol
 to the parent source code directory.
# Path is relative to the sonar-project.properties file. Replace "\" by "/" on Windows.
# Since SonarQube 4.2, this property is optional. If not set, SonarQube starts looking for source code
# from the directory containing the sonar-project.properties file.
sonar.sources=src

# Encoding of the source code
sonar.sourceEncoding=UTF-8

# Additional parameters
sonar.my.property=value

...

Code Block
languagenone
sonar-runner

Security

SonarQube 3.7+

Any user who's granted Execute Analysis permission can run an analysis.

If the Anyone group is not granted Execute Analysis permission or if the SonarQube instance is secured (the sonar.forceAuthentication property is set to true), the credentials of a user having been granted Execute Analysis permission have to be provided through the sonar.login and sonar.password properties. Example: sonar-runner -Dsonar.login=myLogin -Dsonar.password=myPassword

SonarQube 3.4 to 3.6.3

If a project cannot be accessed anonymously, the sonar.login and sonar.password properties are required to run an analysis on this project. These properties have to be set to the credentials of a user having the User role on this project. You can set them either:

  • directly on the command line by adding -Dsonar.login=myLogin -Dsonar.password=myPassword
  • or in the build.xml file

A project cannot be anonymously accessed when either:

Prior to SonarQube 3.4

There is no security restriction.

Project Samples

To help you get started, simple project samples are available for most languages on github. They can be browsed or downloaded. You'll find them filed under projects/languages.

...

Include Page
Include - Analysis - Security
Include - Analysis - Security

Project Samples

To help you get started, simple project samples are available for most languages on github. They can be browsed or downloaded. You'll find them filed under projects/languages.

Multi-language Project

Since SonarQube 4.2, it is possible to run an analysis on a multi-language project. To do so, the sonar.language property just has to be removed. Conversely, if for some reason you want to perform a single language-only analysis, make sure sonar.language is specified.

To help you get started, a multi-language project sample can be browsed or downloaded from github: projects/languages/multi-language/multi-language-java-javascript-sonar-runner

Include Page
Include - Converting a Mono-language Project to a Multi-language Project
Include - Converting a Mono-language Project to a Multi-language Project

Multi-module Project

There are two ways to define a multi-module structure in SonarQube:

 Using the given file structure...... with the given 'properties' files

Way #1

Set all the configuration in the properties file in the root folder

Code Block
title"MyProject/sonar-project.properties" file content
linenumberstrue
languagebash
# Root project information
sonar.projectKey=org.mycompany.myproject
sonar.projectName=My Project
sonar.projectVersion=1.0-SNAPSHOT

# Some properties that will be inherited by the modules
sonar.sources=src

# List of the module identifiers
sonar.modules=module1,module2

# Properties can obviously be overriden for
# each module - just prefix them with the module ID
module1.sonar.projectName=Module 1
module2.sonar.projectName=Module 2

Way #2

Set the configuration in multiple properties files

Code Block
title"MyProject/sonar-project.properties" file content
linenumberstrue
languagebash
# Root project information
sonar.projectKey=org.mycompany.myproject
sonar.projectName=My Project
sonar.projectVersion=1.0-SNAPSHOT

# Some properties that will be inherited by the modules
sonar.sources=src

# List of the module identifiers
sonar.modules=module1,module2
Code Block
title"MyProject/module1/sonar-project.properties" file content
linenumberstrue
languagebash
# Redefine properties
# Note that you do not need to prefix the property here
sonar.projectName=Module 1
Code Block
title"MyProject/module2/sonar-project.properties" file content
linenumberstrue
languagebash
# Redefine properties
# Note that you do not need to prefix the property here
sonar.projectName=Module 2

...

  • Modules with the same structure: projects/multi-module/sonar-runner/java-sonar-runner-modules-same-structure
  • Modules with different structures: projects/multi-module/sonar-runner/java-sonar-runner-modules-different-structures
  • A configuration file for each module: projects/multi-module/sonar-runner/java-sonar-runner-modules-own-configuration-file

Multi-module and Multi-language Project

Since SonarQube 3.3, it is possible to run an analysis on a multi-module project whose modules contains source code from different languages.

In addition to the multi-module configuration, the only mandatory property to set is the language for each module:

Code Block
titlemodule.sonar.language
linenumberstrue
languagebash
module1.sonar.language=java
module2.sonar.language=js
...

To help you getting started, a multi-language project sample can be browsed or downloaded from github: projects/languages/multi-language/multi-language-java-javascript-sonar-runner

Running Other Tasks

Before SonarQube 3.6, it was only possible to run a project analysis. Since SonarQube 3.6, it is possible to run other tasks such as:

Code Block
languagebash
# To run the computation of views (Views plugin is required)
sonar-runner views

# To run the computation of reports (Report plugin is required)
sonar-runner report

# To run the computation of developer data (Developer Cockpit plugin is required)
sonar-runner devcockpit

Advanced Usage

If a sonar-project.properties file cannot be created in the root directory of the project, there are several alternatives:

  • The properties can be specified directly through the command line. Ex:

    Code Block
    languagenone
    sonar-runner -Dsonar.projectKey=myproject -Dsonar.sources=src1

      

  • The property 'project.settings' can be used to specify the path to the project configuration file (this option is incompatible with the 'project.home' property and sonar.projectBaseDir properties). Ex:

    Code Block
    languagenone
    sonar-runner -Dproject.settings=../myproject.properties

      

The root folder of the project to analyze can be set through the ' sonar.projectBaseDir property since SonarQube Runner 2.4 (was previously project.home' property). This folder must contain a sonar-project.properties file if the mandatory properties (like sonar.projectKey) are not specified on the command line.

...

Troubleshooting

Note

If you get an a Java heap space error or java.lang.OutOfMemoryError, you can set increase the memory via the SONAR_RUNNER_OPTS environment variable, like this in *nix environments:

Code Block
languagenone
export SONAR_RUNNER_OPTS="-Xmx512m -XX:MaxPermSize=128m"

On Windows environments, avoid the double-quotes, since they get misinterpreted and combine the two parameters into a single one.

Code Block
languagenone
set SONAR_RUNNER_OPTS=-Xmx512m -XX:MaxPermSize=128m

Migrating from SonarQube Runner 1.X to SonarQube Runner 2.0

Replace the following properties in the sonar-project.properties file:

  • sources => sonar.sources
  • tests => sonar.tests
  • binaries => sonar.binaries
  • libraries => sonar.libraries
Explicitly set the sonar.sourceEncoding property in the sonar-project.properties file.