cwltool 3.1.20220913185150

安装

sudo apt-get install cwltool

sudo apt-get update

conda install -c conda-forge cwltool

python3 -m venv env      # Create a virtual environment named 'env' in the current directory
source env/bin/activate  # Activate environment before installing `cwltool`

pip install cwlref-runner

pip install cwltool

git clone https://github.com/common-workflow-language/cwltool.git # clone (copy) the cwltool git repository
cd cwltool           # Change to source directory that git clone just downloaded
pip install .[deps]  # Installs ``cwltool`` from source
cwltool --version    # Check if the installation works correctly

在命令行上运行

简单命令：

cwl-runner [tool-or-workflow-description] [input-job-settings]

或者，如果您安装了多个 CWL 实现并且想要覆盖默认的 cwl-runner，请使用：

cwltool [tool-or-workflow-description] [input-job-settings]

您可以使用 CWLTOOL_OPTIONS 在环境中设置 cwltool 选项，这些选项将插入到命令行的开头：

export CWLTOOL_OPTIONS="--debug"

在 macOS 上与 boot2docker 一起使用

boot2docker 在虚拟机中运行 Docker，它只在其上挂载用户 。CWL 的默认行为是在例如 /Var下创建Docker 容器无法访问的临时目录。

要使用 boot2docker 成功运行 CWL，您需要将--tmpdir-prefix 和--tmp-outdir-prefix设置为/Users下的某个位置：

$ cwl-runner --tmp-outdir-prefix=/Users/username/project --tmpdir-prefix=/Users/username/project wc-tool.cwl wc-job.json

使用 uDocker

出于技术或政策原因，某些共享计算环境不支持 Docker 软件容器。作为一种解决方法，CWL 参考运行程序支持在 Linux 上使用带有--user-space-docker-cmd选项的替代docker实现。

udocker https://github.com/indigo-dc/udocker是这样一种“用户空间”友好的 docker 替代品。

udocker安装：https ://indigo-dc.github.io/udocker/installation_manual.html

像往常一样运行cwltool，但使用新选项，例如，来自一致性测试

cwltool --user-space-docker-cmd=udocker https://raw.githubusercontent.com/common-workflow-language/common-workflow-language/main/v1.0/v1.0/test-cwl-out2.cwl https://github.com/common-workflow-language/common-workflow-language/raw/main/v1.0/v1.0/empty.json

cwltool还可以使用Singularity 2.6.1 或更高版本作为 Docker 容器运行时。 带有 Singularity 的cwltool将运行 DockerRequirement中指定的软件容器，因此仅适用于 Docker 映像，不支持本机 Singularity 映像。要将 Singularity 用作 Docker 容器运行时，请向 cwltool 提供--singularity命令行选项。借助 Singularity，cwltool可以通过所有 CWL v1.0 一致性测试，但涉及 Docker 容器 ENTRYPOINT 的测试除外。

例子

cwltool --singularity https://raw.githubusercontent.com/common-workflow-language/common-workflow-language/main/v1.0/v1.0/v1.0/cat3-tool-mediumcut.cwl https://github.com/common-workflow-language/common-workflow-language/blob/main/v1.0/v1.0/cat-job.json

从远程或本地位置运行工具或工作流

cwltool可以通过其对 HTTP[S] URL 的支持在本地和远程系统上运行工具和工作流描述。

输入作业文件和工作流程步骤（通过运行指令）可以使用绝对或相对本地文件系统路径引用 CWL 文档。如果引用了相对路径并且在当前目录中找不到该文档，则将搜索以下位置：http: //www.commonwl.org/v1.0/CommandLineTool.html#Discovering_CWL_documents_on_a_local_filesystem

您还可以使用cwldep <https://github.com/common-workflow-language/cwldep> 来管理对外部工具和工作流的依赖。

在加载时覆盖工作流要求

有时，工作流需要额外的要求才能在特定环境或特定数据集上运行。为了避免修改底层工作流，cwltool 支持需求“覆盖”。

“覆盖”对象的格式是项目标识符（工作流程、工作流程步骤或命令行工具）到应应用的流程要求的映射。

cwltool:overrides:
  echo.cwl:
    requirements:
      EnvVarRequirement:
        envDef:
          MESSAGE: override_value

可以在命令行上或作为作业输入文档的一部分指定覆盖。使用工作流文件的名称后跟步骤名称作为文档片段标识符“#id”来标识工作流步骤。覆盖标识符与顶级工作流文档相关。

cwltool --overrides overrides.yml my-tool.cwl my-job.yml

input_parameter1: value1
input_parameter2: value2
cwltool:overrides:
  workflow.cwl#step1:
    requirements:
      EnvVarRequirement:
        envDef:
          MESSAGE: override_value

cwltool my-tool.cwl my-job-with-overrides.yml

将工作流程的各个部分组合到一个文档中

使用--pack 将由多个文件组成的工作流程组合成一个复合文档。此操作获取工作流引用的所有 CWL 文件，并在 $graph字段的列表中构建一个包含所有 Process 对象（CommandLineTool 和 Workflow）的新 CWL 文档。交叉引用（例如run:和source: 字段）更新为新打包文档中的内部引用。顶级工作流被命名为#main。

cwltool --pack my-wf.cwl > my-packed-wf.cwl

仅运行工作流的一部分

您可以使用--target ( -t ) 选项运行部分工作流。这采用顶级工作流中的输出参数、工作流步骤或输入参数的名称。您可以提供多个目标。

cwltool --target step3 my-wf.cwl

如果目标是输出参数，它将仅运行有助于该输出的步骤。如果目标是工作流步骤，它将从该步骤开始运行工作流。如果目标是输入参数，它将只运行连接到该输入的步骤。

使用--print-targets获取工作流目标的列表。要查看将运行哪些步骤，请使用--print-subgraph和 --target来获取所选目标的工作流子图的打印输出。

cwltool --print-targets my-wf.cwl

cwltool --target step3 --print-subgraph my-wf.cwl > my-wf-starting-from-step3.cwl

可视化 CWL 文档

--print-dot选项将打印适合 Graphviz dot程序的文件。这是一个 bash onliner，用于生成可缩放矢量图形 (SVG) 文件：

cwltool --print-dot my-wf.cwl | dot -Tsvg > my-wf.svg

将 CWL 文档建模为 RDF

CWL 文档可以表示为 RDF 三元图。

cwltool --print-rdf --rdf-serializer=turtle mywf.cwl

cwltool 中的环境变量

除了标准的EnvVarRequirement之外，此参考实现还支持多种为工具设置环境变量的方法 。用于创建环境的步骤顺序是：

0. 如果存在--preserve-entire-environment标志，则从当前环境开始，否则从空环境开始。

1. 添加由--preserve-environment选项指定的任何变量。

2. 根据CWL v1.0+ CommandLineTool 规范设置TMPDIR和HOME。

3. 应用CommandLineTool描述中的任何EnvVarRequirement 。

4. 应用任何cwltool:MPIRequirement扩展所需的任何操作。

5. 替换Secrets扩展所需的任何秘密。

6. 修改环境以响应SoftwareRequirement（见下文）。

利用软件需求（测试版）

CWL 工具可以使用SoftwareRequirement提示进行修饰，cwltool 可以反过来使用这些提示来解析各种包管理器或依赖管理系统（例如Environment Modules ）中的包。

使用 cwltool使用SoftwareRequirement提示需要一个可选的依赖项，因此请务必在安装 cwltool 时使用指定deps修饰符。例如：

$ pip install 'cwltool[deps]'

以这种方式安装 cwltool 启用了几个新的命令行选项。这些选项中最通用的是--beta-dependency-resolvers-configuration。此选项允许指定依赖解析器的配置文件。该文件可以指定为 XML 或 YAML，并且非常简单地描述了各种插件以启用“解决” SoftwareRequirement依赖项。

使用这些提示将允许 cwltool 修改工具运行的环境，例如通过加载一个或多个环境模块。如上所述构建环境，然后可以通过所选工具解析器修改环境。这目前意味着您无法覆盖所选工具解析器设置的任何环境变量。请注意，为配置的依赖解析器提供的环境将变量_CWLTOOL设置为1以允许自省。

要讨论其中一些插件以及如何配置它们，请首先考虑以下示例 CWL 工具的提示定义。

SoftwareRequirement:
  packages:
  - package: seqtk
    version:
    - r93

现在想象在安装了软件模块的集群上部署 cwltool 并且seqtk模块在版本r93中可用。这意味着默认情况下，集群用户可能不会在他们的PATH上拥有二进制seqtk，但是在使用命令modulecmd sh load seqtk/r93 seqtk在PATH上提供此模块后。一个简单的依赖解析器配置文件，例如，称为 dependency-resolvers-conf.yml，它可以让cwltool在执行上述工具之前获取正确的模块环境，它只是：

- type: modules

外部列表表示正在启用一个插件，插件参数定义为该列表项的字典。上面的插件只有一个必需参数，这是type并定义插件类型。所有插件都需要此参数。可用的插件和每个可用的参数在此处记录（不完整） 。不幸的是，本文档是在 Galaxy 工具 需求而不是 CWL SoftwareRequirement的上下文中，但概念映射相当直接。

cwltool 分发了此类 seqtk 工具和示例相应作业的示例。它可以使用依赖解析器配置文件从 cwltool 根目录执行，例如使用以下命令：

cwltool --beta-dependency-resolvers-configuration /path/to/dependency-resolvers-conf.yml \
    tests/seqtk_seq.cwl \
    tests/seqtk_seq_job.json

此示例演示 cwltool 可以利用现有软件安装，还可以处理依赖于相同软件和库的不同版本的工作流。但是，上面的示例确实需要现有的模块设置，因此无法使用 cwltool “开箱即用”测试此示例。对于演示所有相同概念的更孤立的测试 -可以使用解析器插件类型galaxy_packages 。

“Galaxy 包”是环境模块的一种轻量级替代方案，它实际上只是通过将目录布局到包和版本中以查找用于修改环境的小脚本的方式来定义的。多年来，它们已在 Galaxy 社区中用于使 Galaxy 工具适应集群环境，但既不需要 Galaxy 知识，也不需要任何特殊工具来设置。这些对于 CWL 工具应该可以正常工作。

cwltool 源代码存储库的测试目录设置有一个非常简单的目录，该目录定义了一组“Galaxy 包”（但实际上只定义了一个名为random-lines 的包）。目录布局很简单：

tests/test_deps_env/
  random-lines/
    1.0/
      env.sh

如果启用了galaxy_packages插件并指向 cwltool 根目录中的 tests/test_deps_env目录，并且 遇到如下所示的SoftwareRequirement 。

hints:
  SoftwareRequirement:
    packages:
    - package: <s>'random-lines'</s>
      version:
      - <s>'1.0'</s>

然后 cwltool 将在执行相应的工具之前简单地找到该 env.sh文件并获取它。该env.sh脚本仅负责修改作业的PATH以添加所需的二进制文件。

这是一个完整的示例，因为解析“Galaxy 包”没有外部要求。通过从 cwltool 的根目录执行以下命令来尝试一下：

cwltool --beta-dependency-resolvers-configuration tests/test_deps_env_resolvers_conf.yml \
    tests/random_lines.cwl \
    tests/random_lines_job.json

上面示例中的解析器配置文件很简单：

- type: galaxy_packages
  base_path: ./tests/test_deps_env

给定 CWL 工具中的SoftwareRequirement可能与给定集群的模块名称不匹配。可以使用使用解析器插件参数mapping_files指定的另一个文件将此类要求重新映射到特定的部署包或版本。我们将使用galaxy_packages 来演示这一点，但是这些概念同样适用于环境模块或Conda 包（如下所述）。

所以考虑解析器配置文件。（测试/test_deps_env_resolvers_conf_rewrite.yml）：

- type: galaxy_packages
  base_path: ./tests/test_deps_env
  mapping_files: ./tests/test_deps_mapping.yml

以及对应的映射配置文件（tests/test_deps_mapping.yml）：

- from:
    name: randomLines
    version: 1.0.0-rc1
  to:
    name: random-lines
    version: <s>'1.0'</s>

这就是说如果 cwltool 在工具中遇到1.0.0-rc1版本 的randomLines要求，则将我们的特定插件重写为1.0版本的random-lines。cwltool 有一个名为random_lines_mapping.cwl的测试工具 ，其中包含这样的源SoftwareRequirement。要使用映射尝试此示例，请从 cwltool 根目录执行以下命令：

cwltool --beta-dependency-resolvers-configuration tests/test_deps_env_resolvers_conf_rewrite.yml \
    tests/random_lines_mapping.cwl \
    tests/random_lines_job.json

前面的示例演示了利用现有基础架构来提供对 CWL 工具的要求。如果改为使用真正的包管理器，cwltool 有机会根据需要安装需求。虽然提供了对 Homebrew/Linuxbrew 插件的初始支持，但开发最多的此类插件是用于Conda包管理器的。Conda 具有允许同时安装多个版本的软件包的良好属性，不需要评估权限即可安装 Conda 本身或使用 Conda 的软件包，并且是跨平台的。由于这些原因，cwltool 可以作为普通用户运行，安装自己的 Conda 环境并在 Linux 和 Mac OS X 上管理多个版本的 Conda 包。

Conda 插件可以无休止地配置，但是可以通过简单地传递 cwltool --beta-conda-dependencies标志来启用一组合理的默认值，这些默认值已被证明是 Galaxy 工具开发生态系统中强大的依赖管理堆栈。

有了这个，我们可以在没有 Docker 或任何外部管理服务的情况下使用上面的 seqtk 示例 - cwltool 应该安装它需要的所有东西并为该工具创建一个环境。使用以下命令尝试一下：

cwltool --beta-conda-dependencies tests/seqtk_seq.cwl tests/seqtk_seq_job.json

CWL 规范允许将 URI 附加到SoftwareRequirement以消除包名称的歧义。如果上述映射文件允许部署者调整工具以适应他们的基础设施，那么这种机制允许工具调整他们的需求以适应多个包管理器。为了在 seqtk 的上下文中演示这一点，我们可以简单地打破我们使用的包名称，然后指定一个特定的 Conda 包，如下所示：

hints:
  SoftwareRequirement:
    packages:
    - package: seqtk_seq
      version:
      - <s>'1.2'</s>
      specs:
      - https://anaconda.org/bioconda/seqtk
      - https://packages.debian.org/sid/seqtk

该示例可以使用以下命令执行：

cwltool --beta-conda-dependencies tests/seqtk_seq_wrong_name.cwl tests/seqtk_seq_job.json

用于管理解决这些软件要求的插件框架，作为Galaxy -tool-util的一部分维护- Galaxy 项目的一个小型便携式子集。有关配置和实施的更多信息，请访问以下链接：

• Galaxy中的依赖解析器

• Conda for [Galaxy] 工具依赖项

• 映射文件 - 实现

• 规范 - 实施

• 初始 cwltool 集成拉取请求

与 GA4GH 工具注册表 API 一起使用

Cwltool 可以直接从GA4GH Tool Registry API端点启动工具。

默认情况下，cwltool 搜索https://dockstore.org/。使用--add-tool-registry将其他注册表添加到搜索路径。

例如

cwltool quay.io/collaboratory/dockstore-tool-bamstats:develop test.json

和（未指定版本时默认为最新）

cwltool quay.io/collaboratory/dockstore-tool-bamstats test.json

对于此示例，从https://github.com/CancerCollaboratory/dockstore-tool-bamstats获取 test.json（和输入文件）

wget https://dockstore.org/api/api/ga4gh/v2/tools/quay.io%2Fbriandoconnor%2Fdockstore-tool-bamstats/versions/develop/PLAIN-CWL/descriptor/test.json
wget https://github.com/CancerCollaboratory/dockstore-tool-bamstats/raw/develop/rna.SRR948778.bam

运行需要启动的基于 MPI 的工具

Cwltool 支持对 CWL 规范 http://commonwl.org/cwltool#MPIRequirement的扩展。当工具定义在其要求/提示部分中有此内容，并且 cwltool 已使用--enable-ext运行时，该工具的命令行将扩展为使用 mpirun或类似工具启动它所需的命令。您可以将要启动的进程数指定为文字整数或表达式（将生成整数）。例如：

#!/usr/bin/env cwl-runner
cwlVersion: v1.1
class: CommandLineTool
$namespaces:
  cwltool: "http://commonwl.org/cwltool#"
requirements:
  cwltool:MPIRequirement:
    processes: $(inputs.nproc)
inputs:
  nproc:
    type: int

与容器的交互：MPIRequirement 当前将其命令添加到所构造的命令行的前面。如果您希望并行运行容器化应用程序，对于简单的用例，这确实适用于 Singularity，具体取决于平台设置。但是，这种组合应该被视为“alpha”——请报告您遇到的任何问题！目前这不适用于 Docker。（更准确地说，你会得到n个同时运行的同一个进程映像的副本，它们之间不能相互通信。）

特定于主机的参数在一个简单的 YAML 文件中配置（使用--mpi-config-file标志指定）。下表给出了允许的键；都是可选的。

启用快速解析器（实验性）

对于非常大的工作流程，cwltool可能会在第一步运行之前花费大量时间进行初始化。有一个实验标志--fast-parser可以显着减少初始化开销，但是在撰写本文时它有几个限制：

• 一般来说，错误报告比标准解析器更糟糕，您将希望将它与您知道已经正确的工作流一起使用。

• 它不检查悬空链接（这些将成为运行时错误而不是加载错误）

• 如https://github.com/common-workflow-language/cwltool/pull/1720中所述，其他几个案例都失败了

在本地运行测试

• 运行基本测试（/tests）：

要在安装cwltool后运行基本测试，请执行以下命令：

pip install -rtest-requirements.txt
pytest   ## N.B. This requires node.js or docker to be available

要在所有受支持的 Python 环境中运行各种测试，我们使用tox。要在所有受支持的 Python 环境中运行测试套件，首先克隆完整的代码存储库（参见上面的git clone说明），然后在终端中运行以下命令： pip install tox; 毒物-p

可以使用以下命令查看所有环境的列表： tox --listenvs 并使用以下命令运行特定测试环境： tox -e <env name> 并使用以下格式另外运行特定测试： tox -e py310-unit -- -v tests/ test_examples.py::test_scandeps

• 运行整套 CWL 一致性测试：

CWL 规范的 GitHub 存储库包含一个脚本，该脚本使用cwltest 程序针对大量有效的 CWL 文件测试 CWL 实现

可以在位于https://github.com/common-workflow-language/common-workflow-language/blob/main/CONFORMANCE_TESTS.md的通用工作流语言规范存储库中找到运行这些测试的说明。

作为模块导入

添加

import cwltool

到你的脚本。

使用 cwltool 从 Python 运行工具或工作流的最简单方法是使用工厂

import cwltool.factory
fac = cwltool.factory.Factory()

echo = fac.make("echo.cwl")
result = echo(inp="foo")

# result["out"] == "foo"

CWL 工具控制流程

为维护者提供 cwltool 如何在内部工作的技术大纲。

1. 使用 CWL load_tool()加载文档。

   1. 从文件或 URL 中获取文档

   2. 应用预处理（语法/标识符扩展和规范化）

   3. 根据 cwlVersion 验证文档

   4. 如有必要，将文档更新为最新规范

   5. 使用make_tool()回调构造一个 Process 对象。这会产生一个 CommandLineTool、Workflow 或 ExpressionTool。对于工作流，这会递归地构建每个工作流步骤。

   6. 要为 CommandLineTool、Workflow 或 ExpressionTool 构建自定义类型，请提供自定义make_tool()

2. 迭代 Process 对象的job()方法以获取可运行的作业。

   1. job()是一个生成器方法（使用 Python 迭代器协议）

   2. 每次在迭代中调用job()方法时，它都会返回以下之一：可运行项（具有run()方法的对象）、None（表示当前没有准备运行的工作）或迭代结束（表示该过程已完成。）

   3. 通过调用run()来调用可运行项。这将运行该工具并获得输出。

   4. 输出回调报告进程的输出。

   5. job()可以迭代多次。它将产生当前准备运行的所有工作，然后产生无。

3. Workflow对象创建相应的WorkflowJob和WorkflowJobStep对象以在作业调用期间保持工作流状态。

   1. WorkflowJob 遍历每个 WorkflowJobStep 并确定该步骤的输入是否准备就绪。

   2. 当一个步骤准备就绪时，它会为该步骤构造一个输入对象并迭代工作流作业步骤的job()方法。

   3. 每个可运行项都会返回到顶级运行循环

   4. 当步骤作业完成并接收到输出回调时，作业输出将分配给工作流步骤的输出。

   5. 当所有步骤完成后，中间文件被移动到最终的工作流输出，中间目录被删除，工作流的输出回调被调用。

4. CommandLineTool job() 对象产生单个可运行对象。

   1. CommandLineTool job()方法调用make_job_runner()创建一个 CommandLineJob对象

   2. job方法通过设置公共属性来配置CommandLineJob对象

   3. job 方法对 CommandLineTool 的文件和目录输入进行迭代，并创建一个“路径映射”。

   4. 文件从它们的“已解析”位置映射到它们将在工具调用时出现的“目标”路径（例如，Docker 容器内的位置）。目标路径在命令行上使用。

   5. 使用 Docker 卷绑定（使用容器时）或符号链接（如果没有）将文件暂存到目标路径。此暂存步骤使文件能够独立于其源布局进行逻辑重新排列或重命名。

   6. CommandLineJob的run()方法执行命令行工具或 Docker 容器，等待其完成，收集输出，并进行输出回调。

扩展点

以下函数可以传递给 main() 以覆盖或增加列出的行为。

执行人

executor(tool, job_order_object, runtimeContext, logger)
  (Process, Dict[Text, Any], RuntimeContext) -> Tuple[Dict[Text, Any], Text]

顶级工作流执行循环的实现应同步运行流程对象以完成并返回输出对象。

版本函数

()
  () -> Text

返回版本字符串。

logger_handler

logger_handler
  logging.Handler

用于记录的处理程序对象。

可以在 LoadingContext 中设置以下函数来覆盖或增加列出的行为。

fetcher_constructor

fetcher_constructor(cache, session)
  (Dict[unicode, unicode], requests.sessions.Session) -> Fetcher

使用提供的缓存和 HTTP 会话构造一个 Fetcher 对象。

解析器

resolver(document_loader, document)
  (Loader, Union[Text, dict[Text, Any]]) -> Text

将相对文档标识符解析为可以获取的绝对标识符。

可以在 RuntimeContext 中设置以下函数来覆盖或增加列出的行为。

构造工具对象

construct_tool_object(toolpath_object, loadingContext)
  (MutableMapping[Text, Any], LoadingContext) -> Process

用于从文档构造 Process 对象（例如 CommandLineTool）对象的钩子。

选择资源

selectResources(request)
  (Dict[str, int], RuntimeContext) -> Dict[Text, int]

接受资源请求并将其转化为具体的资源分配。

make_fs_access

make_fs_access(basedir)
  (Text) -> StdFsAccess

返回一个文件系统访问对象。

此外，在提供 Process 对象的自定义子类时，可以重写以下方法：

CommandLineTool.make_job_runner

make_job_runner(RuntimeContext)
  (RuntimeContext) -> Type[JobBase]

创建并返回一个作业运行器对象（这实现了命令行工具的具体执行）。

Workflow.make_workflow_step

make_workflow_step(toolpath_object, pos, loadingContext, parentworkflowProv)
  (Dict[Text, Any], int, LoadingContext, Optional[ProvenanceProfile]) -> WorkflowStep

创建并返回工作流步骤对象。