第二章 环境搭建：安装Cromwell、Java环境配置、本地运行第一个WDL工作流

说实话，环境搭建这事看着琐碎，但栽过跟头的人都知道——配好了后面全顺，配不对一步一个坑。我以前帮团队排查过一个问题，折腾了两天才发现是Java版本不对。所以这一章，咱们稳扎稳打。

2.1 Java环境配置

Cromwell 是 JVM 上的应用。运行时依赖 Java 8 或 11。我个人习惯用 Java 11，长支持版本，省心。

2.1.1 检查已有Java

你先打开终端，敲一句：

java -version

如果返回类似 openjdk version "11.0.18" 或 1.8.0_xxx，说明已经装了。如果提示找不到命令，那就去装一个。

2.1.2 安装Java（以Ubuntu为例）

sudo apt update
sudo apt install openjdk-11-jdk

装完再跑 java -version 确认。Windows 用户去 Adoptium 下载 msi 安装包，下一步到底就行。

2.1.3 设置JAVA_HOME（可选但推荐）

很多工具会读这个环境变量。我遇到过一次 Gradle 构建失败就是因为没配 JAVA_HOME。配一下不费事：

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

想永久生效，就塞到 ~/.bashrc 或 ~/.zshrc 里。

2.2 下载与安装Cromwell

Cromwell 发布的是一个 fat jar。说白了就是一个大 JAR 包，包含所有依赖。下载步骤特别简单：

1. 去 GitHub Releases 页面：https://github.com/broadinstitute/cromwell/releases
2. 找到最新稳定版（比如 85），下载 cromwell-85.jar

或者直接用命令行：

wget https://github.com/broadinstitute/cromwell/releases/download/85/cromwell-85.jar

下载后我通常放 ~/tools/cromwell/ 里，好管理。

2.2.1 验证安装

java -jar ~/tools/cromwell/cromwell-85.jar --version

如果输出类似 Cromwell 85-xxxxx，就成了。要是报错，八成是 Java 版本不对，回去检查 java -version。

2.3 理解Cromwell的运行模式

Cromwell 有两种启动模式：单机模式（Run）和服务器模式（Server）。我们第一章先用单机模式。服务器模式等到后面讲 REST API 时再涉及。

你想想看，刚学的时候用 Run 模式最直观。一次就跑一个工作流，日志全打在终端上，调试起来方便得很。

2.4 编写第一个WDL工作流

我们写一个最简工作流：接受一个名字，输出 "Hello {name}"。能跑通就是胜利。

2.4.1 WDL文件：hello.wdl

version 1.0

workflow hello_world {
  input {
    String name
  }
  call say_hello {
    input:
      name = name
  }
}

task say_hello {
  input {
    String name
  }
  command {
    echo "Hello ${name}"
  }
  output {
    String greeting = read_string(stdout())
  }
  runtime {
    docker: "ubuntu:latest"
  }
}

2.4.2 输入JSON文件：hello_inputs.json

{
  "hello_world.name": "Cromwell"
}

注意这个 key 的格式：{工作流名}.{输入变量名}。Cromwell 靠这个规则匹配输入。我刚开始经常写错——少了个下划线或多写了个点，跑起来就说 input not found。

2.4.3 执行命令

java -jar ~/tools/cromwell/cromwell-85.jar run hello.wdl -i hello_inputs.json

看到终端刷刷输出一堆日志，最后有这么一行，说明成功了：

[info] workflow output: {"hello_world.say_hello.greeting": "Hello Cromwell"}

2.5 理解执行过程：一张图说清楚

这一节我用一张 SVG 把整套流程串起来。你注意看三个角色：你写的 WDL、Cromwell 引擎、以及底层的计算环境。执行时 Cromwell 会解析 WDL、载入输入、按依赖调度任务、最后收集输出。

2.6 常见问题与排错

我帮你把新手最容易遇到的三类问题列出来，碰到了直接对照查：

2.7 小结

到这一步，你已经在本地搭好了 Cromwell 环境，跑了第一个 WDL 工作流。别看只是输出了一个 "Hello Cromwell"，背后的解析—调度—执行—输出流程，跟日后跑几百个任务的复杂工作流一模一样。把基础打牢，后面学起来才会顺手。