Skip to content

Latest commit

 

History

History
166 lines (125 loc) · 5.8 KB

usage_with_ort.md

File metadata and controls

166 lines (125 loc) · 5.8 KB

Building a bill-of-materials from an ORT file

SPDX-Builder can convert the output of the OSS Review Toolkit Analyzer to a bill-of-materials file in SPDX format while adding detected license information from the License Scanner service . (Note that ORT itself also includes native export to SPDX files.)

This is a two-step process:

  1. Analyze the project using the Analyzer of OSS Review Toolkit (ORT).
  2. Convert the ORT Analyzer output to an SPDX tag-value file.

OSS Review Toolkit

Running ORT

The ORT Analyzer interprets the configuration files of a wide range of package managers to packages with their metadata in a common ORT file format. SPDX-Builder reads this output file as its input.

Typical command line invocation of the ORT Analyzer is:

ort analyze -i <project_directory> -o <result_directory>

Note: To avoid the "this and base files have different roots" error, it is best practice to always provide an absolute path.

or from a pre-packaged Docker file:

docker run -v <project_dir>:/project philipssoftware/ort --info analyze -i /project -o /project/<output_dir>

The ORT Analyzer produces an analyzer-result.yml file in the indicated result directory containing the bill-of-materials of all identified packages in ORT format. (Note that the tool fails if the ORT file already exists.)

ORT Configuration

The repository configuration for ORT is provided by an .ort.yml file in the root of the project:

excludes:
  paths:
    - pattern: <glob_pattern>
      reason: <path_reason>
      comment: "Free text"

The <path_reason> must be any of:

  • BUILD_TOOL_OF
  • DATA_FILE_OF
  • DOCUMENTATION_OF
  • EXAMPLE_OF
  • OPTIONAL_COMPONENT_OF
  • OTHER
  • PROVIDED_BY
  • TEST_OF

Other configuration possibilities of the ORT Analyzer can be found in the ORT repository configuration file documentation .

Note: Suppressing "scopes" in the ORT repository configuration has no influence on the Analyzer, as it collects all metadata. SPDX-Builder will, however, skip the scopes marked for exclusion in the ORT repository configuration file.

SPDX-Builder

Running SPDX-Builder

The output of the Analyzer can be converted to an SPDX tag-value file using SPDX-Builder by:

spdx-builder ort -c <config_yaml_file> --scanner <license_scanner_url> -o <output_file> <ort_yaml_file>

Note: If no "config_yaml_file" is specified, a file name .spdx-builder.yml is expected to exist in the current directory.

Note: If no "output_file" is specified, the output is written to a file named bom.spdx in the current directory. If the file has no extension, .spdx is automatically appended.

SPDX-Builder configuration

Filtering projects

Since the ORT Analyzer reports about any projects (and dependencies) it encounters in its output, SPDX-Builder requires instructions from a separate configuration file to only include the relevant projects in the bill-of-materials file. This is achieved by the following section in a configuration file (with default name .spdx-builder.yml):

projects:
  - id: "<Input project identifier>"
    purl: "pkg:type/namespace/name@version"
    excluded:
      - "<scope>"

The "Input project identifier" is the identifier that is generated by the ORT Analyzer during detection. SPDX-Builder lists all projects found in the ORT file, and marks them with "-" for projects that are skipped and "+" for projects that are included in the SPDX output.

In case the project itself represents a package, its Package URL can be provided in the "purl" field of the project definition.

GLOB patterns can be used to exclude packages in selected "scopes" per project. The remaining scopes that are included are logged by SPDX-Builder during processing.

To speed up ORT Analyzer, a repository configuration file can be added to the scanned project. By excluding paths via GLOB patterns in a configuration file, analysis of irrelevant sub-projects can be avoided.

Providing project metadata

SPDX documents include common information to indicate the purpose and origin of the software bill-of-materials. This information is provided in the "document" section of the YAML configuration file:

document:
  title: "<(Optional) Document title>"
  organization: "<(Optional) Organization name>"
  comment: "<(Optional) Document comment>"
  key: "<(Optional) Document key>"
  namespace: "http://optional/document/namespace/uri"

Manual package metadata curation

It might not always be possible to retrieve the (correct) metadata per package, and some packages may require an explicit choice which license is used. This information can be provided as "curations" in the YAML configuration file:

curations:
  - purl: "pkg:type/namespace/name@version"
    source: "<vcs_tool>+<transport>://<host_name>[/<path_to_repository>][@<revision_tag_or_branch>][#<sub_path>]"
    license: "<(Optional) License>"

The applicable package is identified by the "purl", which references the package by its Package URL.

Some package managers do not provide the complete or correct location of the package source code. For such cases, the "source" location can be provided in SPDX format as override. Some examples of valid source URI's are:

  • https://git.myproject.org/MyProject.jar (Download as source archive)
  • git+https://git.myproject.org/[email protected] (Git over HTTP by release tag)
  • git+ssh://git%40github.com/MyProject.git@hashvalue (Git over SSH by commit hash)
  • git+https://git.myproject.org/MyProject#submodule (As submodule in a mono repo)