.. include:: ../defines.hrst

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 |SonarAdaPlugin| provided with |GNATdashboard| packages supports
|SonarQube| platform for the LTA (long-term support) version (currently
|SonarQubeLTSVersion|).

How |GNAThub| integrates with |SonarQube|
-----------------------------------------

Sonar Ada Plugin
^^^^^^^^^^^^^^^^

|SonarScanner| requires a |SonarQube| Ada plug-in to work on Ada sources.
|SonarAdaPlugin| 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 :file:`sonar-project.properties`
generated by |GNAThub| :program:`sonar-config` plug-in).

To use it in the context of |GNATdashboard|, first deploy |SonarAdaPlugin| 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 |SonarAdaPlugin|.
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).

|SonarScanner|
^^^^^^^^^^^^^^

|GNAThub| execution (see :ref:`getting-started`) generates one |SonarScanner|
configuration file :file:`sonar-project.properties` describing the project being
analyzed (project name, project key, location of the :file:`gnathub.db` file,
...). This is fully generated by the :program:`sonar-config` plug-in of
|GNAThub| and is expected to be used *as-is* by the |SonarAdaPlugin| part of the
|GNATdashboard| product.

|GNAThub| :program:`sonar-config` plug-in regenerates the :file:`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 :program:`sonar-scanner` plug-in is
executed through :command:`--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| |SonarQubeLTSVersion| LTA version, in order to be able to upload
   analysis results into the dashboard the authentication information is mandatory
   and should be provided when the :program:`sonar-scanner` plug-in is executed as
   :command:`--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
   :command:`--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/.


|SonarScanner| reads its settings from two different files:

* the system-wide :file:`$SONAR_RUNNER_HOME/conf/sonar-scanner.properties`
* the project-specific :file:`sonar-project.properties` file provided through
  the :option:`-Dproject.settings` command line argument of |SonarScanner|

See `Analyzing with SonarQube Scanner <http://bit.ly/2g1Fnnx>`_ for more
information on |SonarScanner|.

By default, |GNAThub| will create the |SonarScanner| configuration file, and
launch the |SonarScanner| itself.

This execution is handled by the :program:`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 :file:`sonar-project.properties` has
been generated prior to launching the |SonarScanner|.

.. note::

    |GNAThub| expects :program:`sonar-scanner` or :program:`sonar-scanner.bat`
    to be available on the :envvar:`$PATH`.

|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 :program:`sonar-config` and :program:`sonar-scanner` plug-ins,
use the :command:`Plugins_Off` project attribute
(see :ref:`project-attr-plugins-off`).

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 :ref:`gnathub-switch-incremental` 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
:ref:`gnathub-switch-exec` switch for custom database processing::

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