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

Purpose

The addLatestSnapshot tool is a simple version of the addSnapshot tool. Use addLatestSnapshot when you want to create a snapshot for the latest version of the code base. When the tool has finished, the snapshot is ready to be built and indexed by the buildSnapshot tool.

Snapshots created with this tool are not "tagged"; this means they are subject to the project's snapshot deletion policy for managing automatically added snapshots.

Usage

This tool is run from the command line as follows:

HIDDEN

odasa addLatestSnapshot [--verbose] [--verbosity <level>] [--project <project_name>] 
  [--concurrent] [--name <snapshot_name>] [--variable <key> <value>] 
  [--fail-early] [--overwrite] [--build-dir <path>] 
  [--source-location <path>] [--checkout <cmd>] [--build <cmd>]

HIDDEN

Flags

The addLatestSnapshot tool supports the following flags:

FlagValueExampleNotes
--verbose--

Optional. Output more detailed information about actions. This increases the verbosity to level 4.

Default: level verbosity

--verbosity<level>2

Optional. Define the precise level of reporting required where 0 suppresses all output and 6 reports all levels of detail available. You can use the --verbose flag as shorthand for --verbosity 4 .

Default: 3

--project<path>projects/myproject

Optional, defines the location of the project configuration file to process.

Default: current directory

--concurrent--

Optional, use to allow the concurrent execution of other commands. Use with care.

Default: the snapshot files are locked to other tools until this tool has completed.

--name<name> Version 1.0

Optional, define a name for the snapshot.

Default: revision-date--time

--variable<key><value>
revision release-1.0
Optional, set a variable for the snapshot file or an associated script to process. May be repeated. The snapshot will also inherit all of the project's variables.
--fail-early--

Optional, use to abort checkout if any checkout command returns a failure (non-zero) exit code.

Default: false

--overwrite--

Optional, use to delete any pre-existing snapshot for the current date and create a new snapshot.

Default: when the project file includes a days-between-updates element then a new snapshot is created only if there is no pre-existing snapshot within the minimum period. When the days-between-updates element is undefined or set to 0 then a new snapshot is created regardless of any pre-existing snapshots.

--build-dir<path>build-location/myproject

Optional, defines a custom working directory for all the build commands. This directory must already exist.

Default: the snapshot's source location

--source-location<path>checkout-location/myproject

Optional, define a custom location to store the source for the snapshot. This directory must already exist.

Default: source directory defined by the project file, or ${snapshot}/src if unspecified there

--checkout<cmd>svn co svn+ssh://my.repository ${src}Optional, define a checkout command. May be repeated. Commands are executed in sequence. Overrides any checkout commands defined in the project file.
--build<cmd>mvn -f pom.xmlOptional, define a build command. May be repeated. Commands are executed in sequence. Overrides any build commands defined in the project file.

 

Examples

Running the tool from a project directory:

$projects/myproject> odasa addLatestSnapshot

Calling the tool from a nightly data processing script:

odasa addLatestSnapshot --project ${SEMMLE_HOME}/projects/myproject

where myproject is the project that you want to add a new snapshot to.

Results

When this tool runs it performs the following operations:

  1. Read the project configuration in the current directory or specified by the --project flag.
  2. If days-between-updates is defined as greater than zero, check for an existing snapshot for the current date. If present, then exit unless the --overwrite flag was defined.
  3. Create a new directory for the revision in the directory where the project configuration file is stored (if data files are stored with configuration files) or in the project sub-directory under SEMMLE_DATA if data files are stored separately.
  4. Get the latest version of the code using the checkout commands defined either in the project file or by command-line flags.
  5. Write a snapshot configuration file. If build or build-dir command-line flags were defined, then include this information in the <build> element. Otherwise copy the build information from the project file.
  6. Check the snapshot policy for the project and, where necessary, delete unwanted snapshots.
  7. If all tasks are completed successfully, then exits with code 0.

When the tool is complete, the snapshot is ready to be built and indexed using the buildSnapshot tool.

Expected output

The tool reports the output of all source control checkout commands executed. The output from the checkout commands is also copied to the checkout-log.log file in the log directory of the newly created snapshot. If any problems are encountered then additional information is output. For example:

  • If one or more of the checkout commands fail, then the output will contain a footer with detailed information, starting with the text:

    ************ WARNING: CHECKOUT MAY HAVE FAILED ************
  • The tool supports a single daily snapshot of a project. If this number is exceeded, then no new checkout is performed and the following message is output:

    There is already a checkout of this project for today's date (4 November 2012)

Exit Code

The addLatestSnapshot command exits with a 0 exit code if the snapshot was successfully created or if no new snapshot is required due to the auto-update policy. If there were any errors creating the snapshot, the return value is non-zero and the errors are reported in the output.