CWL Runner Installation

The recommended CWL runner is cwltool, the reference implementation for the CWL standards.

Tip

• Please explore the cwltool docs for latest installation instructions.
• We also recommend to install a software container engine (e.g. Docker or Podman).

Windows

The installation on Windows can be done following the guide here.

1. Install Windows Subsystem for Linux from the Microsoft Store

   

2. Install Debian from the Microsoft Store

   

3. Set Debian as your default WSL 2 distro:

   • Open Windows PowerShell
   • Type wsl --set-default debian and hit enter

4. Install Docker Desktop for Windows

   • Start Docker Desktop and Navigate to Settings
   • Select “Use WSL 2 based engine” in the general tab and apply
   • Select “Enable Integration with my default distro” in the resources tab under WSL Integration

5. Start WSL:

   • Open Windows PowerShell
   • Type wsl and hit enter
   • You may need to specify a username and password if this is your first time using WSL (the password doesn’t show when typing, just type and hit enter)

6. Follow the Instructions for Linux (Debian/Ubuntu) in this tutorial

Linux

For installation on Linux (Debian/Ubuntu):

1. Run sudo apt-get update in the console
2. Install Python 3 if it is not already installed by executing the command sudo apt install python3
3. Install python virtual environment with sudo apt install python3.11-venv
   • You may need to change the version of python, depending on your installation
   • You can check the installed version with python3 --version
4. Create a virtual environment python3 -m venv env
   • The environment is named env here, the name can vary
5. Activate the virtual environment with source env/bin/activate
   • If you want to activate the environment from a different location, you must enter the full path to the installation location
     • e.g. if you installed it in your home directory, you would use source /home/username/env/bin/activate
6. Install the cwltool with pip by running pip install cwltool

Macos

1. Install conda-forge
2. Install cwltool via conda install -c conda-forge cwltool

cwltool usage

Section titled cwltool usage

• If you are on Windows, start the WSL
• Activate the virtual environment source env/bin/activate
  • If you want to activate the environment from a different location, you must enter the full path to the installation location
    • e.g. if you installed it in your home directory, you would use source /home/username/env/bin/activate
• Run cwltool by specifying the CWL Workflow or CommandLineTool description file path and the (optional) inputs file path (you can use relative or full paths):

cwltool path/to/cwlfile.cwl path/to/jobfile.yml

• If you are in an ARC, you can navigate to the runs folder and type wsl in the address line to start the WSL at that location and execute a typical run after activating the virtual environment (see second step) with the command:

cwltool ./myRun/run.cwl ./myRun/run.yml

• CWL copies the relevant files to temporary directories located on the disc where your WSL is installed. If you want them on a different disk for perfomrance/size reasons, you can use the --tmpdir-prefix and --tmp-outdir-prefix options to specify the location of the temporary directories:

cwltool --tmp-outdir-prefix=/mnt/c/Users/myUser/Tempdir/ --tmpdir-prefix=/mnt/c/Users/myUser/Tempdir/ ./myRun/run.cwl ./myRun/run.yml

Minimal example

Section titled Minimal example

Here is a very simplified example to check, that your cwltool installation functions

1. Store the following as echo-tool.cwl

   #!/usr/bin/env cwl-runner
   
   cwlVersion: v1.2
   
   class: CommandLineTool
   
   baseCommand: [echo]
   
   stdout: message.txt
   
   inputs:
     message:
       type: string
       inputBinding:
         position: 1
   
   outputs:
     output:
       type: stdout

2. In the same folder, store the following as job.yml

   message: "I love ARCs and CWL"

3. Now you can execute the tool

   • providing an input directly via CLI:

   cwltool echo-tool.cwl --message "ARCs are great"

   or

   • providing the input via the job.yml:

   cwltool echo-tool.cwl job.yml

4. Both create an output file called message.txt with your specified message.