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

This topic describes how to use the bootstrap command to create a new project.

Overview

This is the recommended method for creating a new project, except where you have access to the project configuration file for a code base that has similar build and checkout commands.

The bootstrap command prompts you to define:

  1. Basic project details – define the name of the project and the language of the code base.
  2. Source code extraction method – define the type and location of the repository used. Optionally, define a specific code version to analyze.
  3. Build method for the code base – define the build location, method and whether or not a clean step is required.

When you have defined the configuration of the project, then the bootstrap command prompts you to decide whether or not to start analysis immediately.

Please note that the bootstrap command has options for creating a new project for the most common systems. If none of the options listed match your system, then please contact support@semmle.com for assistance.

Starting odasa bootstrap

The odasa bootstrap command is normally run from the odasa directory. At the command prompt, enter:

odasa bootstrap

The bootstrap command starts and prompts you to configure a new project. If this fails, then please check that you have set up the environment for Semmle Core correctly (see Setting up the environment).

-

If you want more information for any of the options displayed by the bootstrap command, then enter ? to display a longer explanation of the options.

-

Defining the basic project details

When you run the bootstrap command, you are prompted to define basic information about the project:

  1. Name for the new project – this name must be suitable for use as a directory name and within a URL (that is, it may contain: letters, digits, hyphen - , underscore _ or period . symbols). By default, this project name is used within configuration files and is also displayed within client applications. If required, you can define an alternative display name for the project (see Changing the project name).
  2. Language used by the project - the programming language determines the build options offered by later steps in the process. If the programming languages listed do not include the language that you want to analyze then you should check that your Semmle license includes analysis of this language. If you think that you should have this language included, and it is not listed here, then please contact the support team.

-

A project can only contain source code written in one programming language. If an application contains source code written in more than one language, then we recommend that you create a project for each language and combine the results later for reporting. XML files can be analyzed alongside any programming language.

-

Defining how to fetch the source code

After you have defined the basic project information, the bootstrap command prompts you to define how to fetch the latest version of the source code. In the configuration file this is referred to as a “checkout” command, but any procedure that results in the source code residing in a well-defined place is perfectly adequate, whether it involves an actual “checkout” step or not.

If the “checkout” requires several steps (for example, to pull in code from multiple repositories), enter one of them here and then afterwards edit the configuration file by hand to add the remaining commands (see Tutorial: Advanced project creation for a worked example or Defining checkout commands manually for an overview).

You are prompted to define:

  1. Type of source code repository – define the type of repository used by the source code. If the source code does not use one of the standard repositories listed, then use “Detached”.
  2. Location of the repository – for standard types of repository only, define the URL of the repository. For “Detached” systems, define the absolute path for the source code.
  3. Specific code version? – by default, the latest code version is extracted from the repository and analyzed. Generally it is best to add any historic versions of the code that you require for reference later using the addSnapshot command.

If the source code repository is password protected then you can use a credentials store to keep the username and password for the account used to access the repository secure. See Creating and using a credentials store  for details.

Defining the build method for the code base

For compiled code, after you have defined how to extract the source code, you must define how to build the project. The options displayed depend on the language that you defined for the project (see Defining the basic project details above). You are prompted to define:

  1. Build tool or compiler used by the project – define the appropriate build tool or compiler. If the source code does not use one of the standard options listed, then please contact support@semmle.com for assistance.
  2. Custom working directory required? – by default, the build commands are run from the directory produced by the "checkout" command. If they should be run from a specific subdirectory instead, then enter the subdirectory required.
  3. Configuration file – for build tools or compilers that support a configuration file, define the location/name (for example, for Ant you define the location/name of the build file).
  4. Run a “clean” step before the build command? – not required when each snapshot is built once from a fresh checkout of the code base. Use when you expect to rebuild a snapshot, for example, during configuration of a new system. This option is also required when you use a shared working directory.
  5. Build command – define the command required to build the project. If the build requires several commands, enter one of them here and then afterwards edit the configuration file by hand to add the remaining commands (see Tutorial: Advanced project creation for a worked example and Defining build commands for an overview).

When you have finished defining the build method for the code base, then the bootstrap command reports: "Project configuration created.". That is, a new subdirectory called  <project_name> has been created in the projects directory and details of the configuration are stored in a project file in this subdirectory. After this point, all subsequent prompts from the bootstrap command ask whether you are ready to start analysis of the code base.

Project configuration files are stored in a <project_name> directory created in odasa/projects unless your Semmle Core environment sets the SEMMLE_HOME environment variable to an alternative location. See Setting up the environment for more information about customizing the location for configuration and data files.

Starting analysis of the code base

When the project configuration file has been created, you can either start analysis immediately or exit the command. If you want to customize the configuration or need to modify the extraction or build definition, then you should exit the command (see Managing projects and Managing dashboards for more information about the next steps).

If the project configuration is complete, then you may want to accept some or all of the following options:

  1. Add a snapshot of the code base? – build a snapshot of the code base ready to analyze. This creates a new snapshot directory in the project subdirectory.
  2. Run a set of analyses? – run a set of queries on the snapshot and store the results in SARIF format in the project data directory. 
  3. Export the snapshot as a zip archive? – store the snapshot zip archive in the project data directory, for use with QL IDEs.