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 createProject command allows you to create a new project as a copy of an existing project or a predefined template. If you want to create an entirely new project then you should use the bootstrap tool.

When createProject has finished you must edit the new project file to configure the checkout command for the code base you are adding.

Usage

Run createProject from the command line as follows:

odasa createProject [--verbose] [--verbosity <level>] [--language <lang>]
 [--template <project_directory>] [--autoupdate <update_file>]
 [--policy <policy_file>] [--name <project_label>] [--ram <memory>]
 [--timeout <time>] [--threads <integer>] [--variable <key1> <value1>] [--force]
<new_project_directory>

Flags

createProject supports the following flags:

FlagsValueExampleNotes
--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

--language<language>java

Mandatory, use to define the programming language for the project.

 Click to show the language values supported...


  • C or C++ — language="cpp"
  • C# — language="csharp"
  • Go — language="go"
  • Java — language="java"
  • JavaScript — language="javascript"
  • Python — language="python"
--template<template_directory>projects/HadoopOptional. Create a new project by copying a predefined template or existing project.
--autoupdate<update_file>common/code-update

Optional. Specify a file that defines the <autoupdate> element (checkout and build commands). See project file for details of the format required by the <autoupdate> element.

--policy<policy_file>common/code-policyOptional. Specify a file that defines the <snapshot-policy> element. See project file for details of the format required by the <snapshot-policy> element.
--name<project_label>User-friendly label

Optional. A display name for the project. This option adds an additional <displayName> element to the project file.

Default: the directory name for the new project is used as a display name.

--ram<memory>16gb

Optional. Specify the value of the <ram> element for the project (memory available to run each query).

The value is assumed to be defined in 1024-based megabytes unless a unit is specified. Units are case insensitive.
 Show valid units...
  • k or kb—kilobytes, the value will be rounded to the nearest megabyte
  • m or mb—megabytes, the default unit if none is specified
  • g or gb—gigabytes
  • t or tb—terabytes

--timeout<time>10mins

Optional. Specify the value of the <timeout> element for the project (maximum time available to run each query). The value is assumed to be defined in seconds unless a unit is specified. Units are case insensitive.

 Show valid units...
  • ms — milliseconds, the value will be rounded to the nearest second
  • ssecsecssecond, or seconds — the default unit if none is specified
  • mminminsminute, or minutes — minutes
  • hhrhourhrs, or hours — hours

--threads<integer>2

Optional. Specify the maximum number of threads allowed for any process run on the project—for example, building a snapshot. Set to zero to use threads equal to the number of available processors.

Default: processes are single-threaded.

--variable
<key1> <value1>
REVISION 13152Optional. Set the value of a variable. Variables can be referred to in the project file using the syntax ${REVISION}. Default values for variables are usually defined in a variables file alongside the project configuration file. Variables are particularly useful in conjunction with the --template option to create projects with minor differences (such as source code repository, branch, build directory, or build target).
--force--

Optional. If the target directory already exists then delete it and recreate it.

Default: an error message is output and no change is made to the directory.

<new_project>-projects/ExampleMandatory. The path and name for the new project directory.

If you call createProject with a template file, then any settings defined using a flag will override any existing values from the template project file.

Examples

odasa createProject --template projects/myOldProject projects/myNewProject

The above command creates a new project called myNewProject, using the existing project myOldProject as a template.

odasa createProject --template ${SEMMLE_HOME}/templates/${template} 
   --ram 32gb --timeout 2400s --force --name "My New Project" 
   --policy ${SEMMLE_HOME}/policies/snapshot-policy.xml 
   ${SEMMLE_HOME}/projects/my-new-project

This command specifies:

  • The memory available to run each query (32 GB)
  • The maximum time available to run each query (2400 seconds)
  • The tool will delete and recreate the target project directory, if it already exists
  • A display name of "My New Project" (which will be used for the project in client applications)
  • The location of a file that defines the deletion policy for snapshots as they become dated
  • The path to the new project directory

Results

When this tool runs it creates a new project directory with the name specified. Within this directory it creates a project file:

  • By copying an existing project–when the --template flag is defined. Any additional data defined by flags overrides the data in the template file (for example, the RAM).
  • Using data defined on the command line–the resulting project file contains only the data specified using the flags defined above. You must define a --language--autoupdate--policy--ram and --timeout to create a valid project file.

Expected output

There is no console output unless the project creation fails, for example, if the directory already exists or the user does not have permission to create a new directory.

Exit code

The createProject command exits with a 0 exit code if the project was successfully created. A non-zero exit code indicates that there was a problem.