The ORT Helper Wrapper (orthw) script

orthw is a shell script designed to simplify and speed up common tasks performed when processing ORT scan results. It supports a number of commands, which can be run in the terminal (e.g. Bash). Most of the commands are thin wrappers around the commands provided by ORT's helper CLI.

For example:

• To correct license findings in an open source dependency, you can run orthw pc-create <package-id>, which generates a package configuration file.
• To indicate that certain items are internal to the project (and so license findings should not be reported against them), you can generate scope excludes for your project's .ort.yml file with the command orthw rc-generate-scope-excludes generates scope excludes.

Benefits of orthw

orthw:

• Simplifies common ORT scan review tasks such as clearing found licenses.
• Offers easy to remember CLI commands (but should you forget, run orthw with no arguments to see a complete list).
• Includes commands to format, sort, clean up and generate ORT config files such as .ort.yml and package configuration.
• Is pre-configured to work with the ort-config repository allowing you to re-use the work of other ORT users.

Installation

1. Prerequisites

orthw requires the following tools to be installed on the system where you intend to run it:

• curl
• md5sum
• OpenJDK
• xz

The installation of these tools depends on the operating system:

• Ubuntu Linux:
  • Run: sudo apt install coreutils curl openjdk-18-jdk xz-utils -y
• MacOS:
  • Install HomeBrew and run: brew install curl md5sha1sum openjdk xz
• Windows using Chocolatey and Git Bash
  • Install Chocolatey
  • Run choco install curl md5 microsoft-openjdk
  • Alternatively you can also install Microsoft OpenJDK using Powershell as administrator and run winget search Microsoft.OpenJDK
  • Use Git Bash as your terminal
• Windows using Windows Subsystem for Linux
  • Install Ubuntu on WSL for Windows 10, or Ubuntu on WSL for Windows 11
  • Run sudo apt install curl md5sum openjdk-18-jdk xz-utils -y

To verify that all the tools have installed correctly, open a new terminal and run:

Command	Output starts with
curl --version	curl [VERSION_NUMBER]
java -version	openjdk version [VERSION_NUMBER]
md5sum --version	md5sum/sha1sum [VERSION_NUMBER]
xz --version	xz (XZ Utils) [VERSION_NUMBER]

The next step is to clone the repositories of ORT, ort-config, ScanCode and orthw script. Run the commands shown below in a dedicated directory such as ~/ort-project:

mkdir -p ~/ort-project && \
cd ~/ort-project && \
git clone https://github.com/oss-review-toolkit/ort.git && \
git clone https://github.com/oss-review-toolkit/ort-config.git && \
git clone https://github.com/oss-review-toolkit/orthw.git && \
git clone https://github.com/nexB/scancode-toolkit.git

Finally, create an exports directory which will be used to store exported license finding curations and path excludes.

mkdir -p ~/ort-project/exports

2. Build ORT

Navigate to the directory where you cloned the ORT repository and run its native build command:

cd ~/ort-project/ort && \
./gradlew installDist

3. Create your orthw configuration

• Copy the orthwconfig-template file from the orthw repository into your home directory.

cp ~/ort-project/orthw/orthwconfig-template ~/.orthwconfig

• Open ~/.orthwconfig in a text editor.

• Set ort_home, orthw_home, configuration_home and scancode_home to the location of the ORT, orthw, ORT configuration and ScanCode repositories which you cloned in above Prerequisites, respectively.

  If you followed examples in the previous steps and used a ort-project directory then the contents of ~/.orthwconfig file should be as follows:

configuration_home=~/ort-project/ort-config

ort_home=~/ort-project/ort

scancode_home=~/ort-project/scancode-toolkit

exports_home=~/ort-project/exports

orthw_home=~/ort-project/orthw

4. Make orthw Script Executable Everywhere

To make orthw executable everywhere, add a alias export to your terminal configuration file.

• Use a text editor to open your terminal launch configuration file e.g. ~/.bashrc or ~/.zshrc.
• Add an alias pointing to the orthw script e.g. alias orthw="bash ~/ort-project/orthw/orthw".
• Reload your terminal configuration file e.g. source ~/.bashrc or source ~/.zshrc.

5. Test if Everything Works

Verify that orthw works by running orthw in a new terminal window: orthw should print the full list of available commands and no error messages.

Usage

Follow the Getting Started guide to learn how to use orthw to:

• Initializing a local directory with an ORT scan result
• Generating a Web App report to see scan results in a web browser
• Marking files, directories or package manager scopes in your project as not included in released artifacts
• Checking your project dependencies for security advisories
• Correcting missing or incorrect package metadata
• Marking files or directories in the sources of a dependency as not included in released artifacts
• Correcting a detected license found in package source code
• Listing the licenses found in the sources of a package
• Listing licenses flagged with a policy violation
• Conclude the license for a package

Contributing to orthw and Questions

All contributions are welcome. If you are interested in contributing, please read our contributing guide. To get quick answers to any of your questions we recommend that you join our Slack community.

License

Copyright (C) 2019-2022 HERE Europe B.V.
Copyright (C) 2022 EPAM Systems, Inc.

See the LICENSE file in the root of this project for license details.

OSS Review Toolkit (ORT) is a Linux Foundation project and part of ACT.