OSS Review Toolkit (ORT) Documentation

The synthetic directory contains test projects that do not use a dedicated package manager (like Maven or NPM). Instead, these projects use SPDX files to declare project metadata and dependencies. These projects are used to verify how the ORT handles various dependency declaration patterns using SPDX.

Available test project types:

• inline-packages: Metadata for both the project and all its dependencies is declared within a single SPDX file.
• package-references: The main file declares project metadata and refers to external SPDX files for each individual package's metadata.
• subproject-dependencies: Verifies that subprojects are handled correctly within the dependency tree.
• transitive-dependencies: Verifies that transitive dependencies (dependencies of dependencies) are resolved correctly.
• subproject-conan: An SPDX-based project that specifically refers to Conan packages.

The analyzer is a Software Composition Analysis (SCA) tool that determines the dependencies of software projects within a specified version-controlled input directory (-i). It is the only mandatory tool in the ORT workflow because its output serves as the required input for all subsequent tools.

How it works

The analyzer queries detected package managers to build a tree of transitive dependencies. It does not require modifications to your source code (like build system plugins) if the following preconditions are met:

• Projects use supported package managers in recent versions and follow common best practices.
• Projects can be built in a single step out-of-the-box without custom configuration (e.g., environment variables or build system properties).

Output

The analyzer writes the dependency tree per project into an OrtResult object. This is saved as analyzer-result.yml in the specified output directory (-o). The output format is YAML by default, but can be set to JSON using the -f flag. This file documents the current status of all package-related metadata and can be manually edited or processed by other tools.

The ORT Scanner is a tool that wraps various license and copyright scanners (like FossID or ScanCode) into a common API. This allows you to run different scanners interchangeably and compare their results using a consistent interface.

Key Features:

• Automatic Workflow: If you provide an ORT result file containing analyzer results using the -i flag, the scanner will automatically trigger the downloader to fetch dependency sources before performing the scan.
• Result Reuse: The scanner can use Storage Backends to avoid re-scanning or re-downloading sources that have already been processed. It checks configured storages for existing results before proceeding with a new scan.
• Provenance-Based Optimization: For FileBasedStorage or PostgresStorage, the scanner groups packages by their provenance. This ensures a specific VCS repository revision is scanned only once, sharing the results across all packages from that repository, which significantly improves performance for large repositories.

Includes are used to define which Open Source Software (OSS) is distributed to third parties versus what is used only internally. This is useful for monorepos where you only want to analyze a specific sub-project.

Inclusions apply to paths (files/directories) or scopes (package manager dependency groups like Maven's compile or NPM's devDependencies).

Key Rules:

• Every include must provide a reason (selected from a predefined list) and an optional comment.
• Path patterns use Ant-style glob patterns.
• Scope patterns use regular expressions.
• By default, all scopes are included; using includes: scopes allows you to filter for specific ones.

includes:
  paths:
  - pattern: "src/**"
    reason: "SOURCE_OF"
    comment: "This directory contains the source code of binaries that are distributed."

  scopes:
  - pattern: "src.*"
    reason: "SOURCE_OF"
    comment: "Source code of delivered packages."