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

This topic describes how to create and edit a project file when your code requires multiple or complicated checkout and build commands.

Overview

Project configuration files define the commands required to access your source files and to build your code base. These commands are used when preparing your code for analysis. In most cases a project file, containing all of the necessary detail, can be created interactively using the bootstrap command. However, your project may have a complicated checkout or build procedure that cannot be defined in a single step with bootstrap. In such cases, it may be necessary to modify your project file manually to include your extra commands.

Creating a project file

You can create a new project file using either the bootstrap or createProject commands. The most appropriate method to use depends upon the exact nature of the code base of your new project, as explained below. After you have created a project file you can manually change the following elements:

  • checkout—This defines the commands that are used to get a revision of your code from a source control repository. 
  • build—This defines the commands that are used to build the code base for compiled languages, or the extractor process to run for interpreted languages.
  • source-location—(optional) This defines where the build should occur. 

In addition, you should check that the values defined by the ram and timeout elements are suitable for the new project. For further information, see project file.

Assessing your source code

Each project file provides the checkout, build and source-location information for the files written in a single language in your project. Therefore, if your project consists of more than one language, additional project files are required. You can check exactly which languages are present in a project using the overview command:

  1. Check out the latest version of your source code into a local directory–for further information about adding your code to a local directory see Managing code checkout of large projects.
  2. Move into the directory that the source files have been added to.
  3. Run odasa overview

The command analyzes all files in the new directory and reports the number of files, lines of code, and lines of comment for each file extension that it finds. You must create a separate project file for each language that you want to analyze using one of the approaches outlined below. For further information about the command, see overview.

Using bootstrap to perform the project creation steps

The bootstrap command simplifies the project creation process and is the best command to use if your new code base is not similar to any of your existing projects. In this case, you can use the command to perform the initial and create the project file in the correct format. You can then exit the bootstrap process and continue editing your project file manually, which allows you to add multiple checkout and build commands. You can also specify the directories from where your checkout and build commands should be run.

To create a new project using bootstrap
  1. From the odasa directory, run:
    odasa bootstrap
  2. You will be prompted to supply the information required to create a project, including:
    • The project language.
    • The project source. For example, an SCM repository or a detached source directory.
    • The source location. For example, a repository URL or absolute file path.
    • Information about the build method for compiled languages, such as Java.
    For further information about these prompts, see Getting started: creating a project.
  3. When you have supplied this information, the project file will be created. Next, you will be asked if you would like to automatically add a snapshot of your code in order to start analysis. You should enter n here in order to exit the bootstrap process and continue editing your project file manually.

  4. Edit the project file to include your new checkout and build commands.
  5. When you have finished updating the project configuration, save the file.
  6. You can start analysis by creating a snapshot for the new project. See preparing your code for analysis for more information.

See Defining checkout commands manually and Defining build commands for more detailed information about defining the checkout and build elements. See project file for more information about the elements and their attributes.

Using createProject to copy an existing project

You can create a new project file using the createProject command, by copying an existing project file. This method is useful if the new code base has similar build and checkout commands to an existing project (for example, a different branch of the same repository). When createProject is complete, you can then 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, edit the project file to include your checkout and build commands, in the newly created project directory.

  3. When you have finished updating the project configuration, save the file.
  4. You can start analysis by creating a snapshot for the new project. See preparing your code for analysis for more information.

See Defining checkout commands manuallyDefining build commands and Customizing calls to extractors for more detailed information about defining the checkout and build elements. See project file for more information about the elements and their attributes.

Using createProject to copy a template

You can also create a new project using the createProject command to copy a template file. This method is useful if the new project has similar build and checkout commands to a predefined template. If this is the case run the createProject command as above and specify the path to the template directory using the --template flag. Again, when createProject is complete, you must edit the project file to define the checkout and build commands required for the new code base.

Editing a project file

You can edit a project file using your preferred text editor.

To edit the project file
  1. Open the project file for editing (for example, using nano or vi).
  2. Edit the XML elements as required (see project file for a full overview).
  3. When you have finished editing the project file, save your changes.

Changes to most elements in the project file are applied to all new snapshots created after the change (created using the addSnapshot or addLatestSnapshot command). For further information about changing specific XML elements in the project file, you should refer to: