.. 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:`/gnathub/logs` are output of tools, *e.g.* :file:`codepeer.log` contains the output of the latest |GNATSAS| 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 `_ 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, which means it will extend the initial plug-ins list, 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 allows |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 ("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 |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 | +----------------+-----------------+--------------------------------------------+ | |GNATSAS| | codepeer | Execute |GNATSAS| 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:`--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 :command:`--gnatcheck-hide-exempted`, |GNAThub| will ignore all GNATcheck violation reported in the "Exempted Coding Standard Violations" section of GNATcheck output file. :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:`--sonar-work-dir` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Expects a folder path as argument. This is the directory where the data needed by the :file:`sonar-scanner` will be collected and used by the |SonarAdaPlugin| to upload analysis results to |SonarQube| dashboard. Creates the directory 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:gnatsas --verbose -- -P project.gpr All switches following :command:`--targs:` are passed to ``, 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:`-d` ^^^^^^^^^^^^^ Display progress for use in IDEs. This command is mainly intended for integration in IDEs, e.g. GNAT Studio.