Introduction

The OSS Review Toolkit (ORT) aims to assist with the tasks that commonly need to be performed in the context of license
compliance checks, especially for (but not limited to) Free and Open Source Software dependencies.

It does so by orchestrating a highly customizable pipeline of tools that abstract away the underlying services.
These tools are implemented as libraries (for programmatic use) and exposed via a command line interface (for scripted
use):

• Analyzer - determines the dependencies of projects and their meta-data, abstracting which package
  managers or build systems are actually being used.
• Downloader - fetches all source code of the projects and their dependencies, abstracting which
  Version Control System (VCS) or other means are used to retrieve the source code.
• Scanner - uses configured source code scanners to detect license / copyright findings, abstracting
  the type of scanner.
• Advisor - retrieves security advisories for used dependencies from configured vulnerability data
  services.
• Evaluator - evaluates license / copyright findings against customizable policy rules and license
  classifications.
• Reporter - presents results in various formats such as visual reports, Open Source notices or
  Bill-Of-Materials (BOMs) to easily identify dependencies, licenses, copyrights or policy rule violations.

Installation

From binaries

Preliminary binary artifacts for ORT are currently available via
JitPack. Please note that due to limitations with the JitPack build
environment, the reporter is not able to create the Web App report.

From sources

Install the following basic prerequisites:

• Git (any recent version will do).

Then clone this repository. If you intend to run tests, you need to clone with submodules by running
git clone --recurse-submodules. If you have already cloned non-recursively, you can initialize submodules afterwards
by running git submodule update --init --recursive.

Build using Docker

Install the following basic prerequisites:

• Docker 18.09 or later (and ensure its daemon is running).
• Enable BuildKit for Docker.

Change into the directory with ORT's source code and run docker build -t ort ..

Build natively

Install these additional prerequisites:

• Java Development Kit (JDK) version 11 or later; also remember to set the JAVA_HOME environment variable accordingly.

Change into the directory with ORT's source code and run ./gradlew installDist (on the first run this will bootstrap
Gradle and download all required dependencies).

Basic usage

ORT can now be run using

./cli/build/install/ort/bin/ort --help

Note that if you make any changes to ORT's source code, you would have to regenerate the distribution using the steps
above.

To avoid that, you can also build and run ORT in one go (if you have the prerequisites from the
Build natively section installed):

./gradlew cli:run --args="--help"

Note that in this case the working directory used by ORT is that of the cli project, not the directory gradlew is
located in (see https://github.com/gradle/gradle/issues/6074).

Running the tools

Like for building ORT from sources you have the option to run ORT from a Docker image (which comes with all runtime
dependencies) or to run ORT natively (in which case some additional requirements need to be fulfilled).

Run using Docker

After you have built the image as described above, simply run
docker run <DOCKER_ARGS> ort <ORT_ARGS>. You typically use <DOCKER_ARGS> to mount the project directory to analyze
into the container for ORT to access it, like:

docker run -v /workspace:/project ort --info analyze -f JSON -i /project -o /project/ort/analyzer

You can find further hints for using ORT with Docker in the documentation.

Run natively

First of all, make sure that the locale of your system is set to en_US.UTF-8 as using other locales might lead to
issues with parsing the output of some external tools.

Then install any missing external command line tools as listed by

./cli/build/install/ort/bin/ort requirements

or

./gradlew cli:run --args="requirements"

Then run ORT like

./cli/build/install/ort/bin/ort --info analyze -f JSON -i /project -o /project/ort/analyzer

or

./gradlew cli:run --args="--info analyze -f JSON -i /project -o /project/ort/analyzer"

Running on CI

A basic ORT pipeline (using the analyzer, scanner and reporter) can easily be run on
Jenkins CI by using the Jenkinsfile in a (declarative)
pipeline job. Please see the Jenkinsfile itself
for documentation of the required Jenkins plugins. The job accepts various parameters that are translated to ORT command
line arguments. Additionally, one can trigger a downstream job which e.g. further processes scan results. Note that it
is the downstream job's responsibility to copy any artifacts it needs from the upstream job.

A demo instance of a Jenkins pipeline for ORT will soon be

Getting started

Please see Getting Started for an introduction to the individual tools.

Download OSS Review Toolkit (ORT)