By SonarSource – GNU LGPL 3 –
Issue Tracker –
Sources
|
Features
The SonarQube Scanner is recommended as the default launcher to analyze a project with SonarQube.
Prerequisites
- SonarQube is already installed
- At least the minimal version of Java supported by your SonarQube server is in use
- The language plugins for each of the languages you wish to analyze are installed
- You have read Analyzing Code Source.
Installation
- Expand the downloaded file into the directory of your choice. We'll refer to it as <install_directory> in the next steps.
Update the global settings (server URL) by editing <install_directory>/conf/sonar-scanner.properties:
#----- Default SonarQube server #sonar.host.url=http://localhost:9000
- Add the <install_directory>/bin directory to your path.
You can check the basic installation by opening a new shell and executing the command
sonar-scanner -h
(on Windows platform the command issonar-scanner.bat -h
) . You should get a message like this:usage: sonar-scanner [options] Options: -D,--define <arg> Define property -e,--errors Produce execution error messages -h,--help Display help information -v,--version Display version information -X,--debug Produce execution debug output
If you need more debug information you can add the sonar.verbose
property by adding the command line parameter -Dsonar.verbose=true
.
Usage
Simple Project
Create a configuration file in the root directory of the project: sonar-project.properties
# must be unique in a given SonarQube instance sonar.projectKey=my:project # this is the name displayed in the SonarQube UI sonar.projectName=My project sonar.projectVersion=1.0 # Path is relative to the sonar-project.properties file. Replace "\" by "/" on Windows. # Since SonarQube 4.2, this property is optional if sonar.modules is set. # If not set, SonarQube starts looking for source code from the directory containing # the sonar-project.properties file. sonar.sources=. # Encoding of the source code. Default is default system encoding #sonar.sourceEncoding=UTF-8
Run the following command from the project base directory to launch the analysis:
sonar-scanner
Security
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 analysis token of a user with Execute Analysis permission must be provided through the sonar.login
property. Example: sonar-scanner -Dsonar.login=[my analysis token]
Security
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 analysis token of a user with Execute Analysis permission must be provided through the sonar.login
property. Example: sonar-scanner -Dsonar.login=[my analysis token]
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-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 | "MyProject/sonar-project.properties" file content # Root project information sonar.projectKey=org.mycompany.myproject sonar.projectName=My Project sonar.projectVersion=1.0 # 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 | "MyProject/sonar-project.properties" file content # Root project information sonar.projectKey=org.mycompany.myproject sonar.projectName=My Project sonar.projectVersion=1.0 # Some properties that will be inherited by the modules sonar.sources=src # List of the module identifiers sonar.modules=module1,module2 "MyProject/module1/sonar-project.properties" file content # Redefine properties # Note that you do not need to prefix the property here sonar.projectName=Module 1 "MyProject/module2/sonar-project.properties" file content # Redefine properties # Note that you do not need to prefix the property here sonar.projectName=Module 2 |
Noteworthy:
- Children inherit their parent's properties
Inherited properties can be overriden:- By prefixing them with the module identifier (way #1)
- Simply by defining them in the sonar-project.properties file located in the module (way #2)
- Module base directory can be specified for special cases
By default, the module base directory is guessed from the module identifier (like in the examples above). But it can be redefined using thesonar.projectBaseDir
property.
For instance, here are two use cases and how to redefine the base directory of the modules in each:the folder of a module contains white spaces or special characters:
module1.sonar.projectBaseDir=My Module One
the module is not located directly in the parent folder, but in a deeper directory structure:
module1.sonar.projectBaseDir=modules/mod1 module2.sonar.projectBaseDir=modules/mod2
- A project that defines modules (or a module that defines sub-modules) cannot define a source code folder to be analyzed.
To help you get started, multi-module project samples can be browsed or downloaded from github:
- 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
Advanced Usage
sonar-project.properties
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:
sonar-scanner -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 theproject.home
andsonar.projectBaseDir
properties). Ex:sonar-scanner -Dproject.settings=../myproject.properties
The root folder of the project to analyze can be set through the sonar.projectBaseDir
property since SonarQube Scanner 2.4 (was previously project.home
). This folder must contain a sonar-project.properties file if the mandatory properties (like sonar.projectKey
) are not specified on the command line.
Additional analysis parameters can be defined in this project configuration file or through command-line parameters.
Alternate Analysis Directory
If the files to be analyzed are not in the directory where the analysis starts from, use the sonar.
projectBaseDir
property to move analysis to a different directory. E.G. analysis begins from jenkins/jobs/myjob/workspace but the files to be analyzed are in ftpdrop/cobol/project1.
sonar.projectBaseDir=/home/ftpdrop/cobol/project1 sonar.sources=src sonar.cobol.copy.directories=/copy
For more, see the listing of analysis parameters.
Troubleshooting
If you get a Java heap space error or java.lang.OutOfMemoryError, you can increase the memory via the SONAR_SCANNER_OPTS environment variable:
export SONAR_SCANNER_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.
set SONAR_SCANNER_OPTS=-Xmx512m -XX:MaxPermSize=128m