This topic describes snapshots and how they are used in Semmle analysis.
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 (
Typically, the above commands are used in either an:
- Automated process—a script runs and calls
addLatestSnapshotto checkout the latest version of the code, followed by
buildSnapshotto generate the database. This script is normally set up to run every night or following every check-in.
- Manual process—you can call
addSnapshotto add a historic version of the code and then use
buildSnapshotto 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
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,
AppTwo, might contain the following snapshot directories:
In this case, the
revision-branch-1 subdirectories contain snapshots added manually. The
revision-2017-December-* subdirectories contain nightly snapshots.