Ctrl+K

1.2. 学习前的准备#

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

CWL 实现

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

1.2.1. 操作系统#

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

  • Linux

  • macOS

  • Windows

备注

If you are using Windows, you will have to install the Windows Subsystem for Linux 2 as documented in the cwltool documentation for Microsoft Windows users. Your operating system also needs internet access and a recent version of Python (3.6+).

1.2.2. CWL 运行程序#

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

cwltool can be installed with pip, apt, or conda. We recommend using a virtual environment like venv or conda.

备注

Visit the cwltool documentation for details on installing 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.1.20240508115724
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.1.20240508115724
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/97mtux49$ true
INFO [job true.cwl] completed success
{}INFO Final process status is success

1.2.2.1. Generic cwl-runner alias#

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

The CWL community publishes a Python package with the name cwlref-runner that installs an alias for cwltool under the name cwl-runner.

用 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.1.20240508115724
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.1.20240508115724
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/65y0d5ul$ 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.1.20240508115724
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/i191kzn3$ true
INFO [job true_shebang.cwl] completed success
{}INFO Final process status is success

备注

The shebang is the two-character sequence #! at the beginning of a script. When the script is executable, the operating system will execute the script using the executable specified after the shebang. It is considered a good practice to use /usr/bin/env [executable] rather than using a hard-coded location, since /usr/bin/env [executable] looks for the [executable] program in the system PATH,

1.2.3. 文本编辑器#

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

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

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. 了解更多信息#

On this page
Edit on GitHub
显示源代码