10. 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 Message Files and Review File which are usually the ones that need to be copied/versioned in order to share or back up your results.

10.1. 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 Comparing GNAT SAS Runs), as well as the last review that applies to it, if any.

The default name of the generated SAM file is <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 <prj>.<timeline>.sam, as seen in Timelines). 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 <object_dir>/gnatsas/<prj>.outputs (or hereafter, <output_dir>) by default. Its location can be customized with the Output_Dir project attribute (see Analyzer package attributes).

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

10.2. Review File

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

Importantly, this file is shared between all the timelines 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.

10.3. Additional artifacts

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

10.3.1. `runs_info` file

The output directory <output_dir> contains a 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.

See also

The switch --list-timelines should be used instead to get user-friendly information about timelines. See Timelines for reference.

10.3.2. GNAT SAS logs

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

10.3.3. Engine-specific outputs

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

10.3.4. Inspector annotations

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