Note: This documentation is for the legacy command-line tool odasa.
The final version was released in May 2020. Support for this tool expires in May 2021.

For documentation on the new generation CodeQL CLI, see CodeQL CLI .
In particular, you may find the Notes for legacy QL CLI users useful in planning your migration.

Skip to end of metadata
Go to start of metadata

HIDDEN

Purpose

Semmle analysis is run against one or more snapshots of a code base. Each snapshot represents the code base as it was after a defined revision.

Each snapshot is stored in a separate snapshot directory and each of these directories includes an XML configuration file called snapshot. The snapshot configuration file is created automatically when the snapshot is added to the project. It includes a definition of where the source code for the snapshot is stored and the commands required to build this code (copied from the project file or defined on the command line at the time of creation). The information is used when the snapshot is built and the snapshot is indexed to create a Semmle snapshot database.

-

In normal operation there is no reason to edit the content of the snapshot file.

-

Structure

The format used for the snapshot file is similar to the format of the project file. The snapshot file uses the following format:

<snapshot>
  <datetime>
    CONTAINS date and time for snapshot
  </datetime>
  <version>
    <datetime>
      CONTAINS a date and time used internally by Semmle
    </datetime>
  </version>
  <source-location>
     CONTAINS details where the snapshot was built
  </source-location>
  <build>
     CONTAINS one or more commands required to build the snapshot
  </build>
</snapshot> 

In addition, a snapshot may contain a <tags> element to define additional meta-data for the snapshot. By default, all snapshots created by the addSnapshot command include:

<tags>
   <tag value="keep"/>
</tags> 

When a <tag> element with a value of keep is present it prevents the snapshot from being deleted by the snapshot deletion policy for the project.

Location

Each snapshot file for a project is stored directly within the snapshot directory. Snapshot directories are located in the project directory. For example, SEMMLE_DATA/projects/myProject.

By convention, snapshot directory names start with revision-. For example, revision-2017-February-24--15-58-48.

The complete path to a snapshot file might therefore be: /opt/semmle/semmleDATAdir/projects/myProject/revision-2017-February-24--15-58-48/snapshot.

Elements

Although the snapshot file uses a similar structure to the project file, there are few user-configurable elements in a snapshot file. In particular, you should not edit data in any of the following elements:

  • <datetime>
  • <version><datetime>
  • <source-location>

In the snapshot file, the <source-location> element is included only after the snapshot has been built. It defines the absolute location of the build. It is never necessary to change this location.

Build configuration

When a snapshot is created, each build command defined in the project file is copied into a <build> element in the snapshot file. This ensures that all snapshots can be rebuilt in the future, even after the build commands defined in the project file have changed to reflect changes to the build process.

Under some circumstances you may need to edit the build commands stored in a snapshot file, but this is not commonly needed. Please see Build configuration in the project file topic for details of the requirements for defining build commands.

Tags element

Any snapshot that contains a <tag> value="keep"</tag> element is ignored when commands apply the snapshot deletion policy for the project. This ensures that any historic snapshots are not accidentally deleted. By default, snapshots created using the addLatestSnapshot command omit this tag and snapshots created using the addSnapshot command include this tag. However, you can also use addSnapshot with the --untagged flag to create a historic snapshot without this element.