.. _GNAT_SAS_Files:

************************
GNAT SAS Files Reference
************************

This chapter describes the files that GNAT SAS creates in order to store the
analysis results, reviews, and information about runs.

The most important ones are :ref:`Sam_Files` and :ref:`Review_File` which are
usually the ones that need to be copied/versioned in order to share or back up
your results.

.. seealso::

	For more information about versioning and sharing of GNAT SAS files, refer
	to :ref:`GNAT_SAS_Workflows` that describes several practical use cases.

.. _Sam_Files:

Message Files
=============

During each analysis run, GNAT SAS creates a Static Analysis Messages (SAM) file
that contains the messages generated by all its analysis engines that were
enabled during the run. This file also contains the age of each message (see
:ref:`GNAT_SAS_Baseline`), as well as the last review that applies to it, if
any.

The default name of the generated SAM file is :file:`<prj>(.<file>).(fast|deep).sam`,
where ``prj`` is the name of the project, ``file`` is the file specified with the
switch ``--file <file>`` or ``--files-from <file>``, and the suffix ``(fast|deep)`` is
describes the analysis mode (note that it can also be described
as :file:`<prj>.<timeline>.sam`, as seen in :ref:`Timeline`). It is possible to
change the name of a run's SAM file by setting the switch ``--run-name <name>``
(the ``.sam`` extension is automatically added if not present in ``name``).

.. warning::

   By default, any new analysis overrides the last run's SAM file, or, if
   ``--run-name <name>`` is set, any run with the same name. To avoid mistakes,
   GNAT SAS does make one backup before doing so (with the ``.backup`` extension).
   However, **we strongly encourage users to version the SAM file along with
   their sources**. This way, the results and sources are kept in sync: later
   on, when checking out a revision of the sources, you will get the analysis
   results associated with that revision.

All the SAM files are generated in the `output directory`, set to
:file:`<object_dir>/gnatsas/<prj>.outputs` (or hereafter, :file:`<output_dir>`)
by default. Its location can be customized with the `Output_Dir` project
attribute (see :ref:`Analyzer_Package_Attributes`).

The output directory also contains the SAM files corresponding to baselines,
named :file:`<prj>(.<file>).(fast|deep).baseline.sam`. GNAT SAS takes care of
copying, renaming, and setting to read-only mode, new baselines' SAM files (see
:ref:`GNAT_SAS_Baseline`).

.. _Review_File:

Review File
===========

User reviews are stored in a Static Analysis Reviews (SAR) file, or simply
`review file`, :file:`<output_dir>/<prj>.sar` by default. Its location can be
customized with the `Review_File` project attribute (see
:ref:`Analyzer_Package_Attributes`).

Importantly, this file is shared between all the :ref:`timelines<Timeline>` and
therefore reviews will apply to the same message in all analyses results,
independently of the analysis mode or other switches used for those analyses.

.. note::

  As for SAM files, we strongly encourage users to version the review file.

.. seealso::

	See :ref:`Reviewing_Results_And_Improving_Code` for more information about
	reviews.

Additional artifacts
====================

These artifacts are generally not relevant to users but may be useful for
debugging purposes.

:file:`runs_info` file
----------------------

The `output directory` :file:`<output_dir>` contains a file
:file:`<prj>.runs_info.json` that provides information about each timeline's
last run and the path to the review file. It is updated each time GNAT SAS is
called.

  .. seealso::

    The switch ``--list-timelines`` should be used instead to get user-friendly
    information about timelines. See :ref:`Timeline` for reference.

GNAT SAS logs
-------------

GNAT SAS log file is generated by default in
:file:`<object_dir>/gnatsas/<prj>.gnatsas/gnatsas.log`, along with some GNAT SAS
internal artifacts.

Engine-specific outputs
-----------------------

Integrated engines generate some internal files and logs under
:file:`<object_dir>/gnatsas/<prj>.<engine>`.

Inspector annotations
---------------------

If Inspector was enabled during the analysis, annotations from Inspector are
generated and stored in subfolders of the `output directory`
:file:`<output_dir>`. Those artifacts can become quite large.