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

Overview

This topic describes the use of Semmle variables. These are used in configuration files and should not be confused with environment variables (which cannot be used directly in configuration files). To distinguish them from environment variables, Semmle variables are written in lowercase letters with underscores separating words—for example  ${semmle_data} is a Semmle variable and $SEMMLE_DATA (or %SEMMLE_DATA% on Windows) is an environment variable.

-

Note

When referring to environment variables in the remainder of this topic the operating-system-specific identifiers ($ and %) have been omitted. For example, references to SEMMLE_HOME mean $SEMMLE_HOME on Linux and OS X, and %SEMMLE_HOME% on Windows.

-

Purpose

Semmle variables can be used to simplify the configuration of analysis and to reduce the use of absolute paths (which make it difficult to relocate a project). Semmle variables can be used almost everywhere in the various configuration files:

  • Project configuration files—in <build> and <checkout> commands, in the <source-location> element and in the dir property of <build> and <checkout> .
  • Snapshot configuration files—in <build> and <checkout> commands, in the <source-location> element and in the dir property of <build> and <checkout> .
  • Query suite files—in @import directives, query and filter definitions (standard pre-defined variables only).
  • QL Test source files—in extractor options for the qltest command.

Semmle variables are referenced with the syntax ${variable_name}. Note that the curly braces are required. At runtime, such a reference is replaced by the value of the variable before the resulting string is interpreted. Spaces within variable values are allowed, but for the purposes of command processing a variable expansion is treated as a single word. For example, take the following build command in a configuration file on a UNIX system:

<build>bash -c ${cmd}</build>

If the ${cmd}  Semmle variable has been set to ls /home, then the string "ls /home" is correctly passed to bash as the second argument, without splitting on white space.

-

Semmle variables are rarely used on the command line, but if you do so you must enclose the variable in quotes to prevent expansion by the shell.

For example:

  • UNIX shells: '${src}'
  • Windows shells: "${src}"
  • never: ${src}

-

Variables can be defined in a number of ways: some are set by the Semmle tools and are always available; others come from the environment of the executing process. Finally, each project can define a set of variables, which are copied and stored in each snapshot when it is created; the snapshot itself can augment this set with further definitions.

Predefined variables

The list of supported variables depends on context.

Project and snapshot configuration files

The following variables are available for use in the project and snapshot configuration files:

VariableSupported inDefinesExample
${semmle_home}
All contexts


The value of the SEMMLE_HOME environment variable (or SEMMLE_DIST if SEMMLE_HOME is unset).

This variable defines the top-level directory where the the queries and tools directories are stored. For more information, see Environment variables.

/directory/config
${semmle_data}

The value of the SEMMLE_DATA environment variable. If SEMMLE_DATA is unset, the value falls back to SEMMLE_HOME or, if that is also unset, to SEMMLE_DIST.

This variable defines the top-level directory for data files generated during analysis. Within the top-level directory, the projects directory contain one subdirectory of data files for each project. For more information, see Environment variables.

/directory/data

${semmle_dist}

The value of the SEMMLE_DIST environment variable. This defines the location of the Semmle Core distribution files, normally a directory named odasa. Under this directory the Semmle Core tools and queries directories are stored. See Environment variables for more information./directory/semmle-core
${odasa_home}

Deprecated.

The value of the deprecated ODASA_HOME environment variable, normally set by running the setup script. This variable has now been replaced by the appropriate semmle_home, semmle_data or semmle_dist variable. Using the semmle_xxxx variables provides increased flexibility for future changes to the deployment of your system.

/directory/odasa
${odasa_tools}The absolute path to the SEMMLE_DIST/tools directory. In older configuration files the equivalent location is: ODASA_HOME/tools/directory/odasa/tools
${odasa_queries}The absolute path to the SEMMLE_DIST/queries directory. In older configuration files the equivalent location is: ODASA_HOME/queries/directory/odasa/queries
${java_home}The value of JAVA_HOME used by Semmle core. This points to the running JVM (Java Virtual Machine)./directory/odasa/tools/java
${project}The absolute path to the current project, typically SEMMLE_HOME/projects/<project_name>. With older configuration files the equivalent location is: ODASA_HOME/projects/<project_name>
/directory/odasa/projects/project_name
${project_data} The absolute path to the directory in which data for the current project is stored, typically SEMMLE_DATA/projects/<project_name> ./directory/data/projects/project_name
${project_name} The name of the project, defined by the name of the folder that contains the project file.project_name
${semmle_cache}

The absolute path to the directory used by Semmle tools as a central cache. The default location is ${semmle_data}/.cache but the environment variable SEMMLE_CACHE can be used to define an alternate location.


/directory/.cache
${snapshot_name}

<checkout> and <build> elements in the project file only

The short name of the current snapshot.

revision-2018-December-01--12-04-42
${snapshot}The absolute path to the current snapshot. This is ${project}/${snapshot_name}/directory/odasa/projects/project_name/
revision-2018-December-01--12-04-42

${src}

The full source location of the snapshot. By default, this is ${snapshot}/src, but can be overridden in the project configuration file using the source location element. See project file for more information./directory/odasa/projects/project_name/
revision-2015-December-01--12-04-42/src

${odasa_home} vs ${semmle_home}, ${semmle_data} and ${semmle_dist}

The ${semmle_home}, ${semmle_data} and ${semmle_dist} variables were introduced in Semmle 1.9.9. They provide greater flexibility than the original, single variable ${odasa_home}. We recommend that you use the newer variables in your configuration files because this will make it easier for you to maintain your installation of Semmle Core. See Environment variables for more information about these environment variables and Large-scale deployments for more information about deploying Semmle Core in large-scale systems.

QL Tester extractor options

The following variables are available for use in extractor options in a QL test.

VariableSupported inDefinesExample
${pwd}All contextsAn absolute path to the directory the command was run from./home/doe/checkout
${testdir}The path to the test case directory, as provided on the command line.tests/qltest/style/EmptyBlock

Variables from the environment

Environment variables can be accessed by prefixing their name with the string "env.". Thus, ${env.PATH} will expand to the value of the PATH environment variable at the time it is evaluated, and ${env.USER} will (at least on UNIX-like systems) hold the current user name. See Environment variables for details of Semmle-specific environment variables.

It is an error to attempt the expansion of an undefined variable. Consequently, only refer to environment variables that are guaranteed to exist at runtime.

Variables from a credentials store

If you want to use a user name and password that are defined in a credentials store, then you can use the semmle_credentials_file variable to define the location of the credentials store to use. This requires you to create a custom variables file, as described in the following section, to define the value of the semmle_credentials_file variable. For credentials stores that were created with an external password, you also need to define the password for the store using the semmle_credentials_password variable (or SEMMLE_CREDENTIALS_PASSWORD environment variable).

After you have created the custom variables files, the user name and password for any account stored in the credentials store can be specified in project and snapshot configuration files using the following variables. This is useful for password-protected source code repositories. See Creating and using a credentials store for details.

VariableSupported inDefinesExample
${alias.username}All contextsThe user name associated with the alias defined.${MyProject-svn.username} where Myproject-svn is an alias in the credentials store.
${alias.password}The password associated with the alias defined.${MyProject-svn.password} where Myproject-svn is an alias in the credentials store.

Custom variables

You can define custom variables to augment a configuration in various ways. This is done in various variables files, each of which specifies the values of a set of variables that can be used in the configuration of either the project or the snapshot. For details, see variables file .