1.2. 学习前的准备#

学习本《用户指南》前，首先需要准备好本节所述的软件及其配置。CWL 标准现有多种工作流运行器和平台实现。本节列出的要求主要着眼于 CWL 的参考运行程序即 cwltool。您也可以使用与之兼容的其他 CWL 运行程序或工作流系统，但运行结果和界面可能有所出入（尽管严格意义上属于工作流的输出应该相同）。

CWL 实现

CWL 标准有多种实现，既包括完整的 CWL 运行程序，也有工作流引擎的插件或扩展程序。详见《实现》一章。

1.2.1. 操作系统#

建议使用以下任一可选系统的最新版本：

Linux
macOS
Windows

备注

如使用 Windows 操作系统，须首先安装适用于 Linux 的 Windows 子系统 2 (WSL2)，详请参阅 cwltool 说明文件针对微软 Windows 用户的部分。同时，您的操作系统还需能接入互联网，以及运行较新版本（3.6 以上）的 Python.

1.2.2. CWL 运行程序#

要运行CWL工作流，首先要用到的就是 CWL 运行程序 (runner). cwltool作为 CWL 社群共同维护开发的 Python 开源项目，正是 CWL 运行程序的参考实现，也就是说，它必须完整支持当前 v1.2 版本 CWL 规约。

cwltool 可通过 pip, apt, 或者conda安装。我们推荐使用venv或conda等虚拟环境。

备注

关于安装cwltoom的详情，请参阅 cwltool 说明文件.

我们来用cwltool 处理名为 true.cwl 的一个简单 CWL 工具描述。

true.cwl#

cwlVersion: v1.2
class: CommandLineTool
inputs: []
outputs: []
# `true` is a Linux command that exits with exit code `0` (success).
baseCommand: "true"

cwltool 命令有一个选项可用于“确认” (validate) 也就是检验 CWL 工具和工作流描述。使用该选项可以进行 CWL 文件语法分析，查找语法错误，并以 CWL 标准验证工作流描述的规范性。然而，进行这一系列操作并不会运行 CWL 文件。要确认 CWL 工作流（包括类似前例的独立命令行工具描述），请将 --validate 选项传递给 cwltool 命令：

用 cwltool 确认（即检验）true.cwl.#

$ cwltool --validate true.cwl
INFO /home/docs/checkouts/readthedocs.org/user_builds/common-workflow-languageuser-guide-zh-hans/envs/latest/bin/cwltool 3.2.20260411152607
INFO Resolved 'true.cwl' to 'file:///home/docs/checkouts/readthedocs.org/user_builds/common-workflow-languageuser-guide-zh-hans/checkouts/latest/src/_includes/cwl/true.cwl'
true.cwl is valid CWL.

去掉 --validate 选项，才能运行 CWL 工具描述：

用 cwltool 运行 true.cwl.#

$ cwltool true.cwl
INFO /home/docs/checkouts/readthedocs.org/user_builds/common-workflow-languageuser-guide-zh-hans/envs/latest/bin/cwltool 3.2.20260411152607
INFO Resolved 'true.cwl' to 'file:///home/docs/checkouts/readthedocs.org/user_builds/common-workflow-languageuser-guide-zh-hans/checkouts/latest/src/_includes/cwl/true.cwl'
INFO [job true.cwl] /tmp/8kp57f2q$ true
INFO [job true.cwl] completed success
{}INFO Final process status is success

1.2.2.1. 通用别名`cwl-runner`#

cwl-runner 是任何符合标准的 CWL 运行程序“不分实现”的别名 (alias). 简言之，cwl-runner 这个别名命令可独立地启用，不依赖于 CWL 运行程序的具体名称。用户只需调用 cwl-runner, 而无需直接调用诸如 cwltool 这样的某个 CWL 运行程序。经系统管理员或用户安装后，cwl-runner 命令用来代指其首选的 CWL 实现。这样的安排更便利于多个 CWL 运行程序共存的环境。

CWL 社群发布有名为 cwlref-runner 的 Python 包，以安装 cwl-runner 作为 cwltool 的别名。

用 pip 为 cwltool 安装别名 cwl-runner.#

$ pip install cwlref-runner

现在要检验或运行工作流就可以用 cwl-runner 这个命令了，它将为你调用 cwltool. 其运行结果和输出应当与上一节中相同。

用 cwl-runner 检验 true.cwl.#

$ cwl-runner --validate true.cwl
INFO /home/docs/checkouts/readthedocs.org/user_builds/common-workflow-languageuser-guide-zh-hans/envs/latest/bin/cwl-runner 3.2.20260411152607
INFO Resolved 'true.cwl' to 'file:///home/docs/checkouts/readthedocs.org/user_builds/common-workflow-languageuser-guide-zh-hans/checkouts/latest/src/_includes/cwl/true.cwl'
true.cwl is valid CWL.

用 cwl-runner 运行 true.cwl.#

$ cwl-runner true.cwl
INFO /home/docs/checkouts/readthedocs.org/user_builds/common-workflow-languageuser-guide-zh-hans/envs/latest/bin/cwl-runner 3.2.20260411152607
INFO Resolved 'true.cwl' to 'file:///home/docs/checkouts/readthedocs.org/user_builds/common-workflow-languageuser-guide-zh-hans/checkouts/latest/src/_includes/cwl/true.cwl'
INFO [job true.cwl] /tmp/5t_0xnjz$ true
INFO [job true.cwl] completed success
{}INFO Final process status is success

执行 cwl-runner 还有一种方法，即直接调用 CWL 文件。为此，首先将 true.cwl 工作流复制为新文件 true_shebang.cwl, 然后加入特定的 shebang (即 "hash-bang") 作为首行：

true_shebang.cwl#

#!/usr/bin/env cwl-runner

cwlVersion: v1.2
class: CommandLineTool
inputs: []
outputs: []
# `true` is a Linux command that exits with exit code `0` (success).
baseCommand: "true"

现在，用 chmod u+x 命令将 true_shebang.cwl 设为可执行。

令 true.cwl 可执行。#

$ chmod u+x true.cwl

到此，此 CWL 文件即可在命令行直接执行了。一旦下令执行这个文件，“shebang”所指定的程序 (即 cwl-runner) 将实际执行其余部分。

使用 shebang 运行 true_shebang.cwl.#

$ ./true_shebang.cwl
INFO /home/docs/checkouts/readthedocs.org/user_builds/common-workflow-languageuser-guide-zh-hans/envs/latest/bin/cwl-runner 3.2.20260411152607
INFO Resolved './true_shebang.cwl' to 'file:///home/docs/checkouts/readthedocs.org/user_builds/common-workflow-languageuser-guide-zh-hans/checkouts/latest/src/_includes/cwl/true_shebang.cwl'
INFO [job true_shebang.cwl] /tmp/dmynhgvo$ true
INFO [job true_shebang.cwl] completed success
{}INFO Final process status is success

备注

所谓 shebang 是指脚本起始处 #! 这两个连续字符。如果脚本可执行，操作系统将用紧跟在 shebang 之后写明的可执行程序来执行此脚本。一个好习惯是用 /usr/bin/env [可执行程序名]，而不是硬性编码其所在路径。这是因为 /usr/bin/env [可执行程序名] 所做的事情，是在系统 PATH（命令路径环境变量）下查找 [可执行程序名] 的实际位置，

1.2.3. 文本编辑器#

任何文本编辑器都可以用于 CWL 编程。不过，我们建议使用支持显示 YAML 语法的编辑器。常用的编辑器包括 Visual Studio Code、Sublime、WebStorm、vim/neovim 以及 Emacs 等。

以下 Visual Studio Code 和 WebStorm 的扩展程序支持 CWL 集成，提供自定义语法显示、改进的自动补全等功能：

带 Benten (CWL) 插件的 Visual Studio Code —— https://github.com/rabix/benten#install-vs-code-extension
IntelliJ 的 cwl-plugin 插件 —— https://plugins.jetbrains.com/plugin/10040-cwl-plugin

CWL 社群维护的编辑器和阅览器列表：https://www.commonwl.org/tools/#editors

1.2.4. Docker#

cwltool 使用 Docker 运行指定了软件容器的工具、工作流及工作流步骤。请按照 Docker 文档在您的操作系统中安装 Docker: https://docs.docker.com/。

您无需掌握如何编写和构建 Docker 容器。在接下来的部分里，我们将用现成的 Docker 映像来运行范例，并阐明有无容器的执行模型之间有何不同。

备注

cwltool 支持使用 Docker、Podman、udocker 和 Singularity 运行容器，并支持从非官方容器仓库拉取映像。

1.2.5. 了解更多信息#

下一节《基本概念》之“实现”主题。
Python venv 模块：https://docs.python.org/3/library/venv.html

1.2. 学习前的准备#

1.2.1. 操作系统#

1.2.2. CWL 运行程序#

1.2.2.1. 通用别名cwl-runner#

1.2.3. 文本编辑器#

1.2.4. Docker#

1.2.5. 了解更多信息#

1.2.2.1. 通用别名`cwl-runner`#