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

Purpose

The variables file allows you to define custom variables that can be used to augment a configuration in various ways. You can define custom variables for:

  • a particular project
  • a particular snapshot

Both of these contexts has its own variable definition file—always called variables

For more information about Semmle variables that can be used in configuration files, see Semmle variables

Format

The format of variables files is that of normal Java properties files. Comments are introduced by a '#' character, and otherwise the file consists of a set of key-value pairs, where the key is the variable name and the value defines what the variable should expand to.

A sample variable definition file
# The MAVEN home to use
M2_HOME = /opt/maven/maven-3.0.4
 
# The MAVEN profile
M2_PROFILE = -Pdebug
 
# The MAVEN invocation
M2_CMD = mvn ${M2_PROFILE} clean install
 
# Windows equivalent of M2_HOME
M2_HOME_WIN = C:\\opt\\maven\\maven-3.0.4

The Java properties specification stipulates that backslashes ('\') are special characters; as a consequence, when giving a Windows path that uses backslash separators, remember to escape them. See the value of the M2_HOME_WIN variable in the example above.

Variable definitions are allowed to reference other variables (see M2_CMD in the example). Note that a variable that directly, or indirectly, depends upon itself is an error (a circular reference).

Variables with names starting "env." are used to refer to environment variables. For example, ${env.SEMMLE_HOME} expands to the value of the SEMMLE_HOME environment variable. Semmle therefore recommends that you do not define project or snapshot variable names that start with "env.". Although these variable names would be valid, the variables may not be expanded to the expected value. The value from the runtime environment would take precedence over the value defined in variable definition file for the project or snapshot.

Locations

The location of the variables file depends on the context in which those variables should be available.

Custom project variables

You can create custom variables for a project in the file ${project}/variables, where ${project} refers to the absolute path to the current project–typically SEMMLE_HOME/projects/<project_name>. The definitions from the project's variables file are available in the project configuration file, and they are copied by addSnapshot and addLatestSnapshot to the snapshot directory in order to initialize the snapshot variable definition file. Additional variables can be defined for the snapshot commands using the --variables flag. 

Setting a custom PATH for project file commands

There are some points you should be aware of if you use the variables file to define a custom PATH for checkout or build commands in the project file.  

 Click for details ...

From Semmle release 1.9.10 onward, if you set a custom PATH in the project variables fileand then include PATH in the export attribute of a checkout or build element in the project file—executables will be looked for in the locations specified by this variable.

Prior to 1.9.10 executables referred to in project file commands were looked for in the PATH of the environment in which the Semmle software is running, rather than the exported PATH.

To ensure the files referred to in commands are found you should either:

  • Use a full path in the command in the project file (e.g. /bin/mkdir rather than simply mkdir).
     

  • In the variables file, add paths to the current PATH, rather than replacing the current PATH.

    For example: PATH=/my/specified/path/:${env.PATH}

Custom snapshot variables

You can define custom variables in the file ${snapshot}/variables, where ${snapshot} refers to the absolute path to the current snapshot. The definitions from the snapshot's variables file are available in the snapshot configuration file. Note that the project's definitions are not directly available to the snapshot, although, as noted above, they are typically copied when the snapshot is created; this allows the project definition to evolve without affecting existing snapshots.

The semmle_credentials_file variable

semmle_credentials_file is a special variable that specifies the location of a credentials store that can be used, for example, to access the source code repository for the project. For example:

semmle_credentials_file=${project}/../credentials.xml

For more information, see Creating and using a credentials store