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

This topic gives an overview of the different methods available for creating a new project.

Overview

A project consists of a subdirectory in the SEMMLE_HOME/projects directory with a project configuration file. See Project for an introduction to projects.

Prerequisites

Before you can create a new project, you need to know the following information for the code base:

  • How to access the source code repository—Semmle Core requires read-only access to the repository
  • How to build or compile the projectSemmle Core analyzes the code base as a system and so must know how the various elements are built or compiled.

Methods available for creating a new project

The main methods for creating a project are:

  • Use the bootstrap command—This guides you through the creation and configuration of a new project. Optionally, you can also choose to create a new dashboard to analyze the project.
  • Use createProject to copy an existing project—This creates a copy of an existing project configuration which you can then edit to define the new project.
  • Use createProject to copy a template—This creates a copy of a template project which you can edit to define the new project. This method is useful for experts if the new code base is substantially different from any currently defined projects.

Using the bootstrap command to create a new project

The simplest way to add a new project is to use the bootstrap command. This method is useful if the new code base is substantially different from any currently defined projects. When you have finished defining the configuration for the project, you need to decide whether or not to create a new dashboard configuration for the new project.

To create a new project using bootstrap
  1. From the odasa directory, run:
    odasa bootstrap
    to start the bootstrap process.
    If this fails, check that you have set up the environment correctly and have a valid Semmle license (see Setting up the environment).
  2. Enter the information requested by the process. To display more detailed information about any option, enter: ?
  3. When the project configuration is complete, decide whether or not to continue and start analyzing the new project.

See Using bootstrap to create a project for more detailed information about using bootstrap or Setting up Project Insight for worked examples that build simple open source projects.

Using createProject to copy an existing project

You can add a new project with createProject, using an existing project as a template. This method is useful if the new code base has similar build and checkout commands to an existing project (for example, a different branch or a new application in the same repository). When createProject is complete, you must edit the project file to modify the checkout and build commands for the new code base.

To copy an existing project using createProject
  1. From the odasa directory, run:
    odasa createProject --template <existing-project-dir> <new-project-dir>
    where <existing-project-dir> is the path to the project directory that you want to copy and <new-project-dir> is the path and name of the new project directory to create.
    If this fails, check that you have set up the environment (see Setting up the environment).
  2. When createProject is complete, you must edit the project file in the newly created project directory. The elements in the project file that must be changed are:

    • checkout—This defines the commands that are used to get a revision from a source control repository. This must be changed to point to the repository of the new project.
    • build—This defines the commands that are used to build the code base. Any paths that refer to directories in the old project need to be changed to point to corresponding directories in the new project.
    • source-location(optional) This defines where the build should occur. If this is specified, then a different value must be given for the new project.
    • displayName(optional) This defines a display label for the project. If this is specified, then change to a suitable label for the new project.
  3. In addition, you should check that the values defined by the snapshot-policy, ram and timeout elements are suitable for the new project.
  4. When you have finished updating the project configuration, save the file.
  5. You can start analysis by creating a snapshot for the new project using the addLatestSnapshot command.

See Defining checkout commands manually and Defining build commands for more detailed information about defining the checkout and build elements or project file for a reference topic.

Using createProject with a template

You can add a new project using the createProject command to create a project from a template file. This method is useful if the new project has similar build and checkout commands to a predefined template. When createProject is complete, you must edit the project file to define the checkout and build commands required for the new code base.

To create a project from a template
  1. From the odasa directory, run:
    odasa createProject --template <template-dir> <new-project-dir>
    where <template-dir> is the relative path to the template directory that you want to copy and <new-project-dir> is the path and name of the new project directory to create.
    If this fails, check that you have set up the environment (see Setting up the environment).
  2. When createProject is complete, you must edit the project file in the newly created project directory. The elements in the project file that must be changed are:

    • checkout—This defines the commands that are used to get a revision from a source control repository. This must be changed to point to the repository of the new project.
    • build—This defines the commands that are used to build the code base.
    • source-location(optional) This defines where the build should occur. If this is specified, then check that the value is suitable for the new project.
  3. In addition, you should check that the values defined by the snapshot-policy, ram and timeout elements are suitable for the new project.
  4. When you have finished updating the project configuration, save the file.
  5. You can start analysis by creating a snapshot for the new project using the addLatestSnapshot command.

See Defining checkout commands manually and Defining build commands for more detailed information about defining the checkout and build elements or project file for a reference topic.