Semmle 1.19
Skip to end of metadata
Go to start of metadata

This topic describes snapshots and how they are used in Semmle analysis.

Overview

Analysis of a project is performed on one or more snapshots of the code. Each snapshot contains all of the code for a specific version of the code base plus a relational database. You access a copy of your revision by defining either specific checkout commands or the location of a detached source directory in the project file. The project file also details the build process for compiled languages, which is used to generate the database. Analysis is carried out on this snapshot database.

How are snapshots created?

You can access your source code and add a copy to your project using one of the following commands:

  • Use addLatestSnapshot command—to check out the current version of the code.
  • Use addSnapshot command—to check out a specific version of the code.

After running one of these commands, the source code files are stored in a buildable state in a src subdirectory or in a detached directory. Output from the checkout commands is available in log/checkout-log.log. No database has been generated, therefore to prepare your snapshot database you must:

  • Use buildSnapshot command—to build and index the copy of the source code.

The resulting snapshot database is stored in a working subdirectory. Output from the build and index commands is available in the log subdirectory. The output subdirectory contains an archive of the source code files that will be used when client applications display source files (src_archive.zip). 

Typically, the above commands are used in either an:

  • Automated process—a script runs and calls addLatestSnapshot to checkout the latest version of the code, followed by buildSnapshot to generate the database. This script is normally set up to run every night or following every check-in.
  • Manual process—you can call addSnapshot to add a historic version of the code and then use buildSnapshot to compare the current quality of the code with previous released versions.

Snapshots created in this way can be analyzed by one or more queries and you can integrate the results of analysis into a tool that supports code review. All log files generated during the add and index processes are archived in the log/log.zip file. Output from the analysis is available in log/analysis.log file.

Location

The files that comprise a snapshot are stored in a snapshot-specific subdirectory of the project directory—for example, SEMMLE_DATA/projects/myProject/<snapshot-directory>. The name of each snapshot subdirectory, by convention, starts withs revision- and follows the pattern revision-yyyy-mmm-dd--hh-mm-ss unless you define otherwise. The name of the directory itself is not necessarily important, as any directory under the project directory containing a snapshot configuration file named snapshot is treated as a valid snapshot.

Example: a team with two projects to analyze, AppOne and AppTwo, might contain the following snapshot directories:

  projects/
    AppOne/
      project
      revision-release-1/
      revision-release-2/
      revision-2017-December-01--00-01-02/
      revision-2017-December-02--00-14-55/
    AppTwo/
      project
      revision-branch-1/
      revision-2017-December-01--00-04-21/
      revision-2017-December-02--00-18-52/

In this case, the revision-release-1, revision-release-2 and revision-branch-1 subdirectories contain snapshots added manually. The revision-2017-December-* subdirectories contain nightly snapshots.

What are the main tasks for a snapshot?

Administrator tasks for a snapshot include: