4. Integrating GNATdashboard into your workflow

GNATdashboard provides an integration with the SonarSource software. SonarQube is an open platform to manage code quality. It is extensible with plug-ins to add support for new languages and rules.

The Sonar Ada Plugin provided with GNATdashboard packages supports SonarQube platform for the LTS (long-term support) version (currently 9.9).

4.1. How GNAThub integrates with SonarQube

4.1.1. Sonar Ada Plugin

SonarQube Scanner requires a SonarQube Ada plug-in to work on Ada sources. Sonar Ada Plugin is provided to this effect and is part of the GNATdashboard package. It is configured to read the SQLite database populated by GNAThub and its plug-ins (it reads its configuration in sonar-project.properties generated by GNAThub sonar-config plug-in).

To use it in the context of GNATdashboard, first deploy Sonar Ada Plugin into your SonarQube instance (please refer to SonarQube manual for plug-ins installation).

The SonarQube dashboard integrates technical debt information, which can be used to assess the amount of effort needed to fix the reported problems. For the Ada language, these values are reported through the Sonar Ada Plugin. This information is available to any analysis tools that might use these values as part of their analysis. Note that, for most rules violation, the remediation cost is constant per issue, and it depends on the rule severity (one one of the following values: Trivial, Easy, Medium, Major, High or Complex).

4.1.2. SonarQube Scanner

GNAThub execution (see Getting started) generates one SonarQube Scanner configuration file sonar-project.properties describing the project being analyzed (project name, project key, location of the gnathub.db file, …). This is fully generated by the sonar-config plug-in of GNAThub and is expected to be used as-is by the Sonar Ada Plugin part of the GNATdashboard product.

GNAThub sonar-config plug-in regenerates the sonar-project.properties configuration file each time it is executed. This file is a project configuration file and does not contain authentication credentials in it. In order to authenticate, these parameters could be passed explicitly when the sonar-scanner plug-in is executed through --targs: switch tool specific parameters, eg.:

$ gnathub -P project --plugins sonar-scanner --incremental
       --targs:sonar-scanner -Dsonar.projectKey=<project_key>
       -Dsonar.login=<sonar_login> -Dsonar.password=<sonar-password>

Note

For SonarQube 9.9 LTS version, in order to be able to upload analysis results into the dashboard the authentication information is mandatory and should be provided when the sonar-scanner plug-in is executed as --targs: switch parameters. Instead of passing through explicit login/password information, we recommend the usage of tokens to authenticate. Once generated, the token could be passed as --targs: parameter, eg.:

$ gnathub -P project --plugins sonar-scanner --incremental
       --targs:sonar-scanner -Dsonar.projectKey=<project_key>
       -Dsonar.login=<myAuthenticationToken>

To know more about how to generate and use the tokens please refer to the official SonarQube documentation related to Generating and Using Tokens at https://docs.sonarqube.org/latest/user-guide/user-token/.

SonarQube Scanner reads its settings from two different files:

  • the system-wide $SONAR_RUNNER_HOME/conf/sonar-scanner.properties

  • the project-specific sonar-project.properties file provided through the -Dproject.settings command line argument of SonarQube Scanner

See Analyzing with SonarQube Scanner for more information on SonarQube Scanner.

By default, GNAThub will create the SonarQube Scanner configuration file, and launch the SonarQube Scanner itself.

This execution is handled by the sonar-scanner plug-in of GNAThub. This is always scheduled as the last GNAThub plugin: this ensures that the output of all other tools is available in the GNAThub database and that sonar-project.properties has been generated prior to launching the SonarQube Scanner.

Note

GNAThub expects sonar-scanner or sonar-scanner.bat to be available on the $PATH.

4.2. GNATdashboard without SonarQube

SonarQube is only used to display results from various analyses.

The technical debt information is also available in the SonarQube dashboard for the issues reported by the supported tools. It is therefore not mandatory to display the analysis: for instance, you can choose not to use the SonarQube integration but use custom scripting to extract the analysis results stored in the GNAThub database.

To disable the sonar-config and sonar-scanner plug-ins, use the Plugins_Off project attribute (see Plugins_Off).

4.3. Incremental analysis

GNAThub can be configured to run one plug-in at a time and thus provides incremental execution of each plug-in (allowing for finer grain control and better integration in existing project and code base).

Use --incremental (short option -i) to enable incremental mode:

$ for plugin in gnatcheck gnatmetric codepeer; do
>   gnathub --incremental --plugins $plugin -P project.gpr
> done

$ gnathub --incremental --plugins sonar-config -P project.gpr
$ gnathub --incremental --plugins sonar-scanner -P project.gpr
         --targs:sonar-scanner -Dsonar.login=<myAuthenticationToken>

If you do not wish to use the SonarQube integration, you can simply omit the last two GNAThub executions and use the --exec switch for custom database processing:

$ gnathub --exec my-results-collector.py -P project.gpr