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

This topic describes how to install the software for Semmle Core (previously known as odasa). Semmle Core is used to analyze code bases and generate data for all Semmle applications apart from Semmle Mend local analysis, where the local code base is analyzed from within the developers' IDE.

Overview

You need to install Semmle Core on a server only if the server does not already have an installation of Semmle Core. A single installation of Semmle Core can support several instances of Team Insight, or the standalone analysis of many projects and dashboards.

Before you install Semmle Core

Before you can install Semmle Core you need:

  • The appropriate Semmle Core zip file for the operating system of the computer on which you want to install Semmle Core.
  • A valid Semmle license file.

Semmle Core requires a Java 8 JRE. By default, Semmle Core uses the Java 8 JRE that is bundled with the distribution zip file.

-

Customers can download a zip file containing Semmle Core by logging into the Semmle customer wiki and browsing to the Downloads page.

-

Selecting an installation directory

The installation of Semmle Core does not require administrative rights on most systems. It can be installed in any directory that is writeable by the current user. Other common considerations apply:

  • Spaces in the path should be avoided, since they may complicate the quoting required for certain commands.
  • Ideally, Semmle Core should be installed either on local storage, or a network mount with good input/output (IO) performance.
  • There should be sufficient disk space: The base installation takes around 900 MB of disk space.
  • On Windows, there are OS-imposed restrictions on the maximum length of paths. It is advisable to choose a fairly short path for the installation directory.

Examples of common choices include:

  • Linux/OS X/home/$USER/odasa  or /opt/odasa
  • Windows: C:\odasa

Most Semmle Core commands are the same under Apple OS X, Linux and Windows (although any file paths must be defined using the appropriate delimiter symbol for the environment). In cases where a command is not the same on all the supported operating systems, other than the file path, all versions of the command are shown.

The location of the odasa directory is referred to throughout the documentation as SEMMLE_DIST. This denotes the $SEMMLE_DIST (Linux/OS X) or %SEMMLE_DIST% (Windows) environment variable, which specifies the location.

Installation

You install Semmle Core by unpacking the zip file. Note that extracting the distribution archive will create a subdirectory called odasa/ and put all other files within it, so if you want the location of Semmle Core to be /opt/odasa, extract the archive directly into the /opt directory.

To install ODASA
  1. Place the zip file in the directory where you want to install Semmle Core.
  2. Unzip the zip file. For example, on Linux you might use: unzip -q odasa-1.12.0-linux64.zip

When you have finished installing Semmle Core, you are ready to set it up and begin analysis.

Setting up Semmle Core

Before you can begin analysis, you need to make a few decisions about where to store the files associated with Semmle Core, that is: the Semmle license file, analysis configuration files and the data generated. The options available support all use cases, from simple test systems to large-scale deployments.

A standard installation of Semmle Core has four key components:

  1. Semmle Core installation—the odasa directory created above
  2. Semmle license file
  3. Configuration files and, optionally, custom queries to define the analysis required
  4. Data files generated by Semmle analysis.

The locations where these different components are stored can all be defined using environment variables, so it is easy to change their location as your needs vary. For a prototype or test system, it is simplest to store all the files relating to Semmle analysis in the same location as Semmle Core (SEMMLE_DIST). For most other use cases, is better to store the other components in a separate location as this makes it much easier when you want to upgrade to a new version of Semmle Core. 

Basic set up—prototypes

You can store all the components for Semmle Core in the main odasa directory, created during installation. All you need to do is to create a license directory for your Semmle license.

  1. Create a license sub-directory in your odasa directory.
  2. Move your Semmle license file into the new subdirectory.
  3. Run the setup script:
    • Linux/OS Xsource setup.sh
    • Windowssetup.bat
    This sets the SEMMLE_DIST environment variable to the location of the odasa directory, and puts all the Semmle Core commands on the path. You will need to run this script when you open a new shell for Semmle analysis (see Setting up the environment for information about automating this).

When you run Semmle analysis, all configuration and data files will be created in subdirectories of the odasa directory. You are ready to start analysis.

Standard set up—easily maintained

You can choose to store the license file, configuration files and data files in a separate location from the Semmle Core files. This set up is much simpler to upgrade than the basic set up described above. You need to create a directory to store all the files used and created by Semmle analysis, then set the SEMMLE_HOME environment variable to define this location.

  1. Create a directory for the files used and created by Semmle analysis, for example:  /home/$USER/semmle-analysis or C:\semmle-analysis.
  2. Create a license subdirectory in this location and move your Semmle license file into it.
  3. Set the SEMMLE_HOME environment variable to the location of the directory created in step 1 (see Large-scale deployments for information about related environment variables).
  4. Run the setup script:
    • Linux/OS Xsource setup.sh
    • Windowssetup.bat
    This sets the SEMMLE_DIST environment variable to the location of the odasa directory, and puts all the Semmle Core commands on the path. You will need to run this script when you open a new shell for Semmle analysis (see Setting up the environment for information about automating this).

You will need to repeat the last two steps when you open a new shell for Semmle analysis (see Setting up the environment for information about automating this).

When you run Semmle analysis, all configuration and data files will be created in subdirectories of the directory defined by SEMMLE_HOME. You are ready to start analysis.

If you want to store the configuration and data files in separate locations, for example, to simplify back-ups, see Large-scale deployments for more information.

Directory structure of Semmle analysis

Semmle Core

The odasa directory contains the following important sub-directories. You should not need to edit or update any of the files in these directories :

DirectoryDescription

tools

Contains all Semmle Core and third-party binaries. You should not need to use this directly as all functions are provided by the odasa command. This directory should only be changed during an update to Semmle Core.

queries

Contains the standard queries available to analyze code. Each query file is written using the QL language and defines either a rule to test or a metric to calculate. Documentation for each query is also stored in this location.

templates

Contains standard templates for projects and dashboards. These can be used to create new projects or dashboards either indirectly using the bootstrap process or directly using the createProject command.

Semmle analysis files

The directories used for the Semmle license file, configuration files and data files are as follows:

DirectoryDescription
license Contains your Semmle license file

projects

Will contain a sub-directory for each project you set up for analysis. If you have a Basic or Standard set up, each subdirectory contains both the configuration files for Semmle analysis and the data files generated.

dashboards Will contain a sub-directory for each dashboard you set up for standalone analysis (Project Insight). If you have a Basic or Standard set up, each subdirectory contains both the configuration files for Semmle analysis and the data files generated.
team-insight Will contain a sub-directory for each instance of Team Insight you configure. If you have a Basic or Standard set up, each subdirectory contains both the configuration files for Semmle analysis and the data files generated.
repositories Will contain a sub-directory for each repository you set up for Team Insight analysis.

The entire Semmle Core directory structure can be moved. You can also use environment variables to control the location of these directories, and to store the data files in a separate location from the configuration files (see Environment variables and Large-scale deployments for more information).