SonarScanner CLI
The SonarScanner CLI is the scanner to use when there is no specific scanner for your build system.
The SonarScanner does not yet officially support ARM architecture. Still, early adopters reported it is working fine. If you encounter problems, don't hesitate to share your experience with us on the SonarQube or SonarCloud Community Forum but keep in mind that there is no support at this time.
The SonarScanners run on code that is checked out. See Verifying the code checkout step of your build.
Configuring your project
Create a configuration file in your project's root directory called sonar-project.properties
.
Running SonarScanner CLI from the zip file
To run SonarScanner CLI from the zip file, follow these steps:
- 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 to point to your SonarQube server:
- Open the
$<INSTALL_DIRECTORY>/conf/sonar-scanner.properties
file. - Uncomment and edit the
#sonar.host.url=
http://localhost:9000
line to point to your SonarQube server URL.
- Open the
- Add the
<INSTALL_DIRECTORY>/bin
directory to your path. - Verify your installation by opening a new shell and executing the command
sonar-scanner -h
, orsonar-scanner.bat -h
on Windows. You should get an output like this:
usage: sonar-scanner [options]
Options:
-D,--define <arg> Define property
-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 one of the following to your command line:-X
,--verbose
, or-Dsonar.verbose=true
. - Run the following command from the project base directory to launch analysis and pass your authentication token:
sonar-scanner -Dsonar.token=myAuthenticationToken
Alternatively, instead of passing the token in your command line, you can create theSONAR_TOKEN
environment variable and set the token as its value before you launch the analysis.
- 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 to point to your SonarQube server:
- Open the
$<INSTALL_DIRECTORY>\conf\sonar-scanner.properties
file. - Uncomment and edit the
#sonar.host.url=
http://localhost:9000
line to point to your SonarQube server URL.
- Open the
- Add the
<INSTALL_DIRECTORY>\bin
directory to your path. - Verify your installation by opening a new shell and executing the command
sonar-scanner -h
, orsonar-scanner.bat -h
on Windows. You should get an output like this:
usage: sonar-scanner [options]
Options:
-D,--define <arg> Define property
-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 one of the following to your command line:-X
,--verbose
, or-Dsonar.verbose=true
. - Run the following command from the project base directory to launch analysis and pass your authentication token:
sonar-scanner -Dsonar.token=myAuthenticationToken
Alternatively, instead of passing the token in your command line, you can create theSONAR_TOKEN
environment variable and set the token as its value before you launch the analysis.
Running SonarScanner CLI from the Docker image
To scan using the SonarScanner CLI Docker image, use the following command:
When running the container you have to make sure the user 1000 has read and write access to the directories you are mounting (like your source code or scanner cache directory), otherwise you may encounter permission-related problems.
Caching scanner files
To prevent SonarScanner from re-downloading language analyzers each time you run a scan, you can mount a directory where the scanner stores the downloads so that the downloads are reused between scanner runs. On some CI systems, you also need to add this directory to your CI cache configuration.
The following command will store and use cache between runs:
You can also change the location of where the scanner puts the downloads with the SONAR_USER_HOME
environment variable.
The user must have the appropriate access to the cache target to avoid permission-related problems
Scanning C, C++, or Objective-C projects
Scanning projects that contain C, C++, or Objective-C code requires some additional analysis steps. You can find full details on the C/C++/Objective-C language page.
Sample projects
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 sonarqube-scanner/src
.
Alternatives to 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. Example:
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 thesonar.projectBaseDir
property). Example:
sonar-scanner -Dproject.settings=../myproject.properties
- The root folder of the project to analyze can be set through the
sonar.projectBaseDir
property since SonarScanner CLI 2.4. This folder must contain asonar-project.properties
file ifsonar.projectKey
is 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
. This is configured in sonar-project.properties
as follows:
You can configure more parameters. See Analysis parameters for details.
Advanced configuration
If your SonarQube server is secured
If your SonarQube server is configured with HTTPS and a self-signed certificate then you must add the self-signed certificate to the trusted CA certificates of the SonarScanner. In addition, if mutual TLS is used then you must define the access to the client certificate at the SonarScanner level.
See Managing the TLS certificates on the client side.
Troubleshooting
Java heap space error or java.lang.OutOfMemoryError
Increase the memory via the SONAR_SCANNER_JAVA_OPTS
environment variable (from SonarScanner CLI version 6.0, or SONAR_SCANNER_OPTS
, otherwise) when running the scanner from a zip file:
In Windows environments, avoid the double quotes, since they get misinterpreted, and combine the two parameters into a single one.
“java” cannot be opened because the developer cannot be verified
The SonarScanner CLI is not yet Apple verified therefore, when using the macOS AArch64 version, you may get an OS security window displaying this message. A solution us to run:
Note that the SonarScanner does not yet officially support ARM architecture. Still, early adopters reported it is working fine. If you encounter other problems when running the scanner on ARM architecture, don't hesitate to share your experience with us on the SonarQube or SonarCloud Community Forum but keep in mind that there is no support at this time.
Unsupported major.minor version
Install the last version of SonarScanner CLI (from version 6.0, no JRE installation is required). Otherwise, upgrade the version of Java being used for analysis or use one of the native package (that embed its own Java runtime).
Property missing: 'sonar.cs.analyzer.projectOutPaths'. No protobuf files will be loaded for this project.
Scanner CLI is not able to analyze .NET projects. Please, use the SonarScanner for .NET. If you are running the SonarScanner for .NET, ensure that you are not hitting a known limitation.
Was this page helpful?