.. _GNAT_SAS_Workflows:

*********
Workflows
*********

There are many different ways to take advantage of GNAT SAS capabilities,
depending on the stage of the project's lifecycle. During development phases,
GNAT SAS can either be run every day or as often as there is a build of some
part of the system. Using GNAT SAS to find defects before a
project enters run time testing minimizes the number of crashes encountered
during testing, allowing functional tests to run to completion and thereby
providing more usable output for test engineers. On existing code being
maintained, it can be used to find potential problems that are not revealed by
testing and which can be extremely difficult to track under deployment. It
can also be used to perform a change impact analysis. In high-integrity and
certification-related environment, it can be used to demonstrate the absence
of certain kind of errors or improve the quality of code review activities.

In all cases, the source code should not be shared directly (say, on a shared
drive) between developers, as this is bound to cause problems with file access
rights and concurrent accesses. Rather, the typical usage is for each user to do
a check-out of the sources/environment, and use therefore their own version/copy
of sources and project files, instead of physically sharing sources across all
users.

This section will describe in detail various ways to put GNAT SAS in
production and give it to the hand of all team members, or only a few
selected ones.

.. note::

  In many workflows below where GNAT SAS is to be run as part of a script,
  you might want to use the ``--quiet`` switch to suppress info output.

.. seealso::

  These workflows assume familiarity with
  :ref:`Getting_the_Right_GNAT_SAS_Settings` which explains how to get the
  proper setting for your specific needs.

Use on a developer machine
==========================

This is the most basic usage: each developer runs GNAT SAS on their own machine,
in ``fast`` mode (see :ref:`Analysis_modes`). Reviews are versioned along the
sources, and are updated by developers when new messages appear.

Thanks to fast mode's incrementality, the developer's machine is not
required to be overly powerful (once an initial analysis has been
performed).


.. _Nightly_Analysis:

Nightly Runs on a Server
========================

In this workflow, GNAT SAS is run nightly on a dedicated server with lots of
resources available (e.g. 16 cores as per :ref:`System_Requirements`),
in ``deep`` mode (set with the switch ``--mode=deep``).

These runs will typically be run nightly to take into account all commits of
the day, and provide results to users the next morning.

The next day, developers can analyze the results, either by checking them out if
they are versioned, or by retrieving them as described in
:ref:`Importing_GNAT_SAS_Results`.

Developers may then review the messages and depending on the outcome, decide to
fix the code or justify the relevant messages, directly in the code or using a
:term:`review file` to be committed. Refer to :ref:`Reviewing_Messages` for the
message review methods, and to :ref:`Export_Import_Reviews` for managing reviews
from multiple users.

.. _Continuous_Analysis:

Continuous Runs on a Server after Each Change
=============================================

In this workflow, GNAT SAS is run on a dedicated server with lots of resources
available (e.g. 16 cores as per :ref:`System_Requirements`) for performing runs
sufficiently rapidly as to provide quick results to users after each commit.
The idea of these runs is not to be exhaustive, but to focus on the differences
from the previous run.

These continuous runs will trigger on a new repository change, typically
integrated with a continuous integration framework such as Jenkins.

At the end of a run, a summary is sent to developers via email or a web
interface, or even directly through GNAT SAS' report formats that are
compatible with forges (e.g. SARIF, or Code Climate for Gitlab).

..
   or Coverity

Once a first analysis has been performed, it is possible to filter the report
of the subsequent analyses in a way that only new messages are shown, for
example with the following command:

.. code-block:: sh

   $ gnatsas report text -Pprj --show age=added

Developers may then review the messages and depending on the outcome, decide to
fix the code or justify the relevant messages, directly in the code or using a
:term:`review file` to be committed. Refer to :ref:`Reviewing_Messages` for the
message review methods, and to :ref:`Export_Import_Reviews` for managing reviews
from multiple users.

.. _Importing_GNAT_SAS_Results:

Importing GNAT SAS Results
==========================

As stated in :ref:`SAM_Files`, GNAT SAS stores the results of a run in a SAM
file, in the :term:`output directory`. Depending on the use case, you may only
have to retrieve this SAM file, or you may need additional elements. We describe
here a few use cases:

* Assuming all project dependencies are available, simply use:

  .. code-block:: sh

    gnatsas report <format> -P <project>

* When all dependencies required in the GPR project are not available in the
  environment, the above command may fail with an explicit error message. It is
  still possible to generate a report from a SAM file without specifying the
  project file by running the command below.

  .. code-block:: sh

    gnatsas report <format> <sam-file>

  ..  warning::

    * The ``<format>`` argument is mandatory.
    * Only the following formats are supported: ``text``, ``csv``,
      ``exit-code``, ``security``, ``gnathub``. Other formats require an
      explicit ``-P <project>`` switch.

* In order to use the results of a distant run as a baseline, or to
  compare local runs to it, retrieve the distant SAM file and use it
  as argument to, either

  .. code-block:: sh

    gnatsas baseline -P<prj> --set-baseline <sam-file>

  or

  .. code-block:: sh

    gnatsas report -P<prj> --compare-with <sam-file>

  You can specify ``--mode <mode>`` on both commands to change the affected mode (see :ref:`Analysis_modes`).

* In order to handle a distant analysis as if it was run locally,
  retrieve the distant SAM file and use it as argument to

  .. code-block:: sh

    gnatsas baseline -P<prj> --set-current <sam-file>

  This way, the imported run is set as the current run (specify
  ``--mode <mode>`` to change the affected mode). The local baseline and
  reviews are applied. You can then display the results with,
  e.g. ``gnatsas report -P<prj>``, add new reviews, etc…

* In order to duplicate the whole state of a distant machine (comprising all
  analysis, baselines and reviews), replace your local :term:`output directory`
  and :term:`review file` with the distant ones. Note that you then lose your
  local state.

.. note::

   You can identify the SAM file of a run with:

   .. code-block:: sh

     gnatsas report -P<prj> --show-header

.. seealso::

  * Refer to :ref:`GNAT_SAS_Workflows` for more information about versioning
    files.
  * Refer to :ref:`CLI_Reference` for more information about GNAT SAS
    command-line switches.

.. _Export_Import_Reviews:

Importing and Sharing GNAT SAS User Reviews
===========================================

When multiple users are reviewing messages locally, they can export their
manual reviews (marking messages as e.g. false positives), in order to
import or share them.

To export manual reviews, the user simply needs to copy the :term:`review file`.

One can then directly incorporate reviews from an external review file with the command

.. code-block:: sh

  gnatsas review -P<proj>.gpr --import <external_review_file>.sar

It is also possible to fuse multiple review files into one with the tool ``merge-reviews``:

.. code-block:: sh

    merge-reviews -o merged.sar <file1.sar> [<fileN.sar>]...

.. note::

  In case of multiple users reviewing the same message, the review that applies
  to the message is always the one with the newest review date (but all reviews
  are kept in the review file).

.. seealso::

  See the :ref:`CLI_Reference` for more details about GNAT SAS command line.

.. _Running_GNAT_SAS_from_Jenkins:

.. include:: jenkins_gnat_sas_plugin.rst

.. _Git_Integration:

.. include:: git_integration.rst

.. _GitLab_Integration:

.. include:: gitlab_integration.rst.inc