2. How to execute the GNAThub driver

2.1. Getting started

Execute GNAThub as you would other GNAT tool. In most cases, you will provide a GNAT project 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 --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.

2.2. Outputs

There are two kinds of log file:

  1. tools output

  2. GNAThub execution log

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

(2) GNAThub uses the same log mechanism as GNAT Studio: the output behavior can be customized through a configuration file. See the GNATcoll Traces documentation for more information.

2.3. Project file attributes

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

2.3.1. General attributes

2.3.1.1. Plugins

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

2.3.1.2. 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.

2.3.1.3. 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, which means it will extend the initial plug-ins list, computed from the [system] and [global] repositories.

The complete list of repositories can be found in GNAThub.repositories().

2.3.2. SonarQube-specific attributes

2.3.2.1. Project_Name

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

2.3.2.2. Project_Version

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

2.3.2.3. Project_Key

Unique key of the project. This is used by the 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 allows SonarQube to discriminate between projects in its database.

2.3.2.4. Source_Encoding

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

2.3.3. 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 ("GNATSAS");
      --  Disable GNATSAS 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

2.4. GNAThub’s core plug-ins

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

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

2.5. GNAThub’s additional plug-ins

An additional [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.

2.6. GNAThub’s command line

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

2.6.1. --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 Plugins. However, the project attribute Plugins_Off still applies to that list and removes any explicitly disabled plug-ins.

2.6.2. --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 --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 --exec switch is used.

2.6.3. --incremental (short option -i)

Takes no argument. Instead of its default behavior, when you specify --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 --incremental switch.

2.6.4. --dry-run (short option -n)

Takes no argument. Instead of its default behavior, when you specify --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.

2.6.5. --gnatcheck-hide-exempted

Takes no argument. This is a GNATcheck specific switch, to be used when GNATcheck plugin is executed, otherwise will have no effect. This switch allows you to specify whether GNATcheck exempted wiolations should be taken into account and added into GNAThub database. Instead of the default behavior (where all exempted violations are imported), when you specify --gnatcheck-hide-exempted, GNAThub will ignore all GNATcheck violation reported in the “Exempted Coding Standard Violations” section of GNATcheck output file.

2.6.6. --target

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

2.6.7. --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.

2.6.8. --sonar-work-dir

Expects a folder path as argument. This is the directory where the data needed by the sonar-scanner will be collected and used by the Sonar Ada Plugin to upload analysis results to SonarQube dashboard. Creates the directory if necessary.

2.6.9. --RTS

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

2.6.10. --jobs (short option -j)

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

2.6.11. --targs:

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

$ gnathub --targs:gnatsas --verbose -- -P project.gpr

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

2.6.12. --runners-only

Takes no argument. Instead of its default behavior, when you specify --runners-only, GNAThub will only execute plugins that implement the 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 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.

2.6.13. --reporters-only

Takes no argument. Instead of its default behavior, when you specify --reporters-only, GNAThub will only execute plugins that implement the 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.

2.6.14. -d

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