gnatdashboard/docs/source/user-manual/execute_driver.rst

.. include:: ../defines.hrst
.. highlight:: console

How to execute the |GNAThub| driver
===================================

.. _getting-started:

Getting started
---------------

Execute |GNAThub| as you would other |GNAT| tool.  In most cases, you will
provide a |GNAT| project file (:file:`.gpr`)::

    $ gnathub -P my_project.gpr

This executes each |GNAThub| plug-in for the project, collects the results
of each tool, and stores those results in its local, temporary,  |SQLite|
database.

|SQLite| is a software library implementing a self-contained, serverless,
zero-configuration, transactional SQL database engine. This makes it a
perfect fit for storing and organizing the results of a single analysis and
making those results available to a wide range of code quality management
platforms.

.. note::

  It is best to consider the |SQLite| database a blackbox.

  This local, temporary, database is intented to be manipulated directly by
  |GNAThub| to store its data, and the recommended way to query data is by using
  the Python API exposed by the tool.

  |GNAThub| will attempt to **reset** the entire database each time it is
  executed, unless given the switch :command:`--incremental` that is designed to
  aggregate the results of different tools into the same database for cases
  where multiple passes cannot be avoided, *eg.*::

      $ gnathub -P project --plugins gnatmetric
      $ gnathub -P project --plugins gnatcheck,gnatcoverage --incremental
      $ gnathub -P project --plugins sonar-config,sonar-scanner --incremental

  Make sure to use the same project across all invocations of gnathub with the
  :commmand:` --incremental` switch.

  It is important to note that |GNAThub| assumes the following properties on the
  |SQLite| database:

    * It must contain at most one set of results per tool;
    * It must contain results for one and only one project and set of sources;
    * It must not be used for persistence (dedicated application such as
      |SonarQube| are intended for this use);
    * Its schema can change from a version to another.

Outputs
-------

There are two kinds of log file:

  1. tools output
  2. GNAThub execution log

(1) Files located in :file:`<object_dir>/gnathub/logs` are output of tools,
*e.g.* :file:`codepeer.log` contains the output of the latest |CodePeer| run
(provided that it was invoked from |GNAThub|). These files are generated if you
invoke the tool using the API function :meth:`GNAThub.Run()`.

(2) GNAThub uses the same log mechanism as |GNATStudio|: the output behavior
can be customized through a configuration file. See the `GNATcoll Traces
documentation <http://docs.adacore.com/gnatcoll-docs/traces.html>`_ for more
information.

Project file attributes
-----------------------

The |GNAThub| driver expects a number of attributes, some required and some
optional, to be set in the project file.

General attributes
^^^^^^^^^^^^^^^^^^

:command:`Plugins`
""""""""""""""""""

List of the names of plug-ins to load and execute for this project. |GNAThub|
ignores this attribute if you specify the :command:`--plugins` switch on the
command line. You can tailor this list by specifying the :command:`Plugins_Off`
attributes.

.. _project-attr-plugins-off:

:command:`Plugins_Off`
""""""""""""""""""""""

List of plug-ins names to remove from the execution queue if present. Use this
to disable one or more plug-ins in the context of a specific project. This
filter is applied after the computation of the complete plug-ins list.

:command:`Local_Repository`
"""""""""""""""""""""""""""

Path to a directory containing custom plug-ins to add to the execution queue of
|GNAThub|. This is a supplementary list of plug-ins, with means it will extend
the initial plug-ins list which is computed from the :command:`[system]` and
:command:`[global]` repositories.

The complete list of repositories can be found in :func:`GNAThub.repositories`.

|SonarQube|-specific attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

:command:`Project_Name`
"""""""""""""""""""""""

Name of the project. This is used by the :file:`sonar-config` plug-in to
override the default project name provided by the |GNAT| project file.

:command:`Project_Version`
""""""""""""""""""""""""""

Version of the project. This is used by the :file:`sonar-config` plug-in to
override the default project version set by the plug-in.

:command:`Project_Key`
""""""""""""""""""""""

Unique key of the project. This is used by the :file:`sonar-config` plug-in
to override the default project key generated by the plug-in (from the
project's name). This is a required attribute that enabled |SonarQube| to
discriminate between projects in its database.

:command:`Source_Encoding`
""""""""""""""""""""""""""

Encoding to use to read files from this project. This is used by the
:file:`sonar-config` plug-in to override the default encoding set
(:command:`UTF-8`) and forward this value to |SonarQube| (which takes care
of reading and indexing all source files).

Example
^^^^^^^

An example is worth a thousand words::

  project My_Project is

     [...]

     package Dashboard is
        for Project_Name use "My_Custom_Project_Name";
        --  Translate to SonarQube Scanner property: sonar.projectName

        for Project_Key use "Custom_Key_For_SonarQube";
        --  Translate to SonarQube Scanner property: sonar.projectKey

        for Project_Version use "1.9.0";
        --  Translate to SonarQube Scanner property: sonar.projectVersion

        for Source_Encoding use "UTF-8";
        --  Translate to SonarQube Scanner property: sonar.sourceEncoding

        for Plugins_Off use ("CodePeer");
        --  Disable CodePeer plug-in

        for Local_Repository use "extra/gnatdashboard_plugins";
        --  Declare a local repository where GNAThub will look for additional
        --  plug-ins.
     end Dashboard;

  end project

|GNAThub|'s core plug-ins
-------------------------

|GNATdashboard|'s driver comes with a set of core plug-ins, available in the
:command:`[system]` repository, allowing quick integration with a software
development team's workflow.

The following tools are currently supported by the |GNAThub|'s core plugins:

+----------------+-----------------+--------------------------------------------+
| **Tool**       | **Plugin name** | **Description**                            |
+----------------+-----------------+--------------------------------------------+
| |GNATmetric|   | gnatmetric      | Execute |GNATmetric| and parse the results |
+----------------+-----------------+--------------------------------------------+
| |GNATcheck|    | gnatcheck       | Execute |GNATcheck| and parse the results  |
+----------------+-----------------+--------------------------------------------+
| |CodePeer|     | codepeer        | Execute |CodePeer| and parse the results   |
+----------------+-----------------+--------------------------------------------+
| |Gcov|         | gcov            | Parse the :file:`.gcov` files              |
+----------------+-----------------+--------------------------------------------+
| |GNATcoverage| | gnatcoverage    | Parse the :file:`.xcov` files              |
+----------------+-----------------+--------------------------------------------+

|GNAThub|'s additional plug-ins
-------------------------------

An additional :command:`[global]` repository is available for the user to store
plugins.  |GNAThub| searches this directory looking for additional plugins
to load. This directory is never overwritten by an update, making it a
good place to store custom plug-ins.

|GNAThub|'s command line
------------------------

You can specify switches on the command line to tune each execution of the
driver. Please use :command:`gnathub --help` to see the full list of
supported switches.

.. _--plugins:

:command:`--plugins`
^^^^^^^^^^^^^^^^^^^^

Expects a comma-separated list of plug-in names as argument. This list is used
as the initial execution queue of the driver, replacing the list of plug-ins
computed from the project attribute :command:`Plugins`. However, the project
attribute :command:`Plugins_Off` still applies to that list and removes any
explicitly disabled plug-ins.

.. _gnathub-switch-exec:

:command:`--exec`
^^^^^^^^^^^^^^^^^

Expects a Python file as argument. Executes the specified Python file after that the
database has been updated. This allows for post-processing, possibly on the local
database, using the exposed Python API. This implies implicit :command:`--incremental`
(retains any previous database) since a post-processing is performed on an already
existing database and the incremental behavior will apply automatically when the
:command:`--exec` switch is used.

.. _gnathub-switch-incremental:

:command:`--incremental` (short option :command:`-i`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Takes no argument. Instead of its default behavior, when you specify
:command:`--incremental`, |GNAThub| retains any previous database (instead of
clearing it). The |GNAThub| database is intended to represent the results
of analysis tools on one single project, so you need pass the same projects
to all invocations of `gnathub` with the :command:`--incremental` switch.

:command:`--dry-run` (short option :command:`-n`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Takes no argument. Instead of its default behavior, when you specify
:command:`--dry-run`, |GNAThub| will report what changes it would have made and
what plugins it would have executed rather than making and executing them. Check
mode is a simulation that can be useful for testing the validity of a command
line and project configuration without running the actual tools.

:command:`--target`
^^^^^^^^^^^^^^^^^^^^

Expects the target name as argument. Used to specify an alternate toolchain.

:command:`--subdirs`
^^^^^^^^^^^^^^^^^^^^

Expects a directory as argument. The database will be located in this
directory relatively from the project object directory. Creates the
subdirectory if necessary.

:command:`--RTS`
^^^^^^^^^^^^^^^^^^^^

Expects an Ada runtime as argument. Forces a specific runtime.

:command:`--jobs` (short option :command:`-j`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expects the maximum number of processes to be executed concurrently as argument.
Similar to the :command:`-j` switch passed to :program:`make`. :command:`0` is a
special value meaning "as many processes as possible". The default is
:command:`1`.

:command:`--targs:`
^^^^^^^^^^^^^^^^^^^

Expects a command line program name and a list of switches to pass to that
program, eg.::

  $ gnathub --targs:codepeer --msg-output-only -- -P project.gpr

All switches following :command:`--targs:<tool>` are passed to `<tool>`,
stopping either at the sentinel `--` or at another :command:`--targs:` option.

:command:`--runners-only`
^^^^^^^^^^^^^^^^^^^^^^^^^

Takes no argument. Instead of its default behavior, when you specify
:command:`--runners-only`, |GNAThub| will only execute plugins that implement
the :class:`GNAThub.Runner` interface. This interface should be implemented by
plugins that need to execute tools to produce results that will be then analysed
by a plugin implementing the :class:`GNAThub.Reporter` interface. Note that the
same plugin can implement both interfaces to encapsulate all the logic to run a
tool and collect its results in the same class.

:command:`--reporters-only`
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Takes no argument. Instead of its default behavior, when you specify
:command:`--reporters-only`, |GNAThub| will only execute plugins that implement
the :class:`GNAThub.Reporter` interface. This interface should be implemented by
plugins that need to process the output of the tool to save its results within
|GNAThub|. Note that the same plugin can implement both interfaces to
encapsulate all the logic to run a tool and collect its results in the same
class.

:command:`--server`
^^^^^^^^^^^^^^^^^^^^

Takes no argument. Launch a WEB server. If `--port` switch is present, then the
server is launched on the specified port. Otherwise, the server will be launched
using a default port which is 8000. Any plugin will be executed.

:command:`--port`
^^^^^^^^^^^^^^^^^^^^

Takes a port number as argument where the web server will be launched. To be
used with `--server` switch in order to specify a custom port for the WEB
server.

:command:`-d`
^^^^^^^^^^^^^

Display progress for use in IDEs. This command is mainly intended for
integration in IDEs, e.g. GNAT Studio.