配置文件看起来像这样

> cat rebuild.hr
plan main {
  reach replace_text
}

task write_text > output=write_text_output.txt {
  echo "foo" > $output
}

task replace_text < input=$output@write_text > output=replace_text_output.txt {
  cat $input | sed 's/foo/bar/' > $output
}

让我们使用上面的配置文件运行上述命令，看看会发生什么

> hr -p main -c rebuild.hr
[command output omitted for brevity]
> tree output
├── branchpoints.txt
├── replace_text
│   ├── Baseline.baseline -> realizations/Baseline.baseline
│   └── realizations
│       └── Baseline.baseline
│           ├── exit_code
│           ├── replace_text_output.txt
│           ├── stderr.txt
│           ├── stdout.txt
│           └── task.sh
└── write_text
    ├── Baseline.baseline -> realizations/Baseline.baseline
    └── realizations
        └── Baseline.baseline
            ├── exit_code
            ├── write_text_output.txt
            ├── stderr.txt
            ├── stdout.txt
            └── task.sh
> cat output/write_text/Baseline.baseline/write_text_output.txt
foo
> cat output/replace_text/Baseline.baseline/replace_text_output.txt
bar

这里发生的事情是，hr创建了一个名为output的目录，其中包含两个任务write_text和replace_text的子目录，在每个这样的目录中都有一个由配置文件中的bash代码创建的.txt文件。

这两个任务都没有任何分支功能，但如果它们有，我们将在每个分支的realizations中看到多个子目录（一个任务在特定工作流程分支上运行时将被实现）。

请注意，所有输出默认都写入到由 hr 调用的目录 hr 下的 output 文件中。这可以通过 -o|--output 选项来覆盖。

另外，hr 还在每个任务的目录中创建了几个附加文件

• exit_code：任务完成后会写入此内容，因此我们可以在之后检查任务是否成功
• stderr.txt 和 stdout.txt：捕获并保存所有来自 bash 代码的输出（它们在任务执行过程中也会写入到控制台）
• task.sh：一个包含产生此任务输出所需的所有命令的 shell 脚本（在实际执行任务时实际上并未使用，但作为调试的归档存在）

重新运行 heron-rebuild

每次调用 hr 时，它都会检查输出目录中已完成的任务，并在可能的情况下使用它们的输出而不重新运行它们。如果在工作流程执行过程中任务的 bash 代码失败，整个工作流程执行将停止，但任何成功的任务仍然可以重复使用。此时，您可以纠正错误，再次调用 hr，而无需重新执行任何之前成功的步骤来完成工作流程。

如果您想强制 hr 重新运行已经成功完成的任务，请参阅下面的 使任务无效 部分。

语法概述

# you must have at least one plan:
plan plan_name {
  reach task_name
}

# variables defined in a global block are available to all tasks:
global {
  unquoted_literal=values/can_be_unquoted
  quoted_literal="values can be in double quotes"

  interpolated="values can interpolate variables, like $unquoted_literal"

  task_output=$output@task_name
}

task task_name
  < literal_input=/home/me/some-file.txt
  > ouput=relative/to/task
  :: param=$unquoted_literal
{
  echo $unquoted_literal
  mkdir -p $(dirname $output)
  cp $literal_input $output
}

详细语法

计划

计划由三个部分组成：一个 名称、一个 目标任务 和一个 分支

plan plan_name {
  reach goal_task via (Profile: debug) * (Os: mac)
}

目标任务由 reach 关键字引入，是我们将从其开始反向创建要执行的任务列表的任务：在 goal_task 的输入中引用的每个任务以及所有依赖任务都将执行，最终在执行 goal_task 后完成工作流程。

分支由 via 关键字引入，并使用笛卡尔积表示法指定。上述 (Profile: debug) * (Os: mac) 分支包含两个 分支点，即 Profile 和 Os，其中 Profile 设置为 debug，而 Os 设置为 mac。

目前，在一个计划中只允许有一个目标任务和一个分支——每个分支点一个值。放宽此限制正在我们的路线图上，一旦完成，您将能够指定例如 (Profile: debug) * (Os: mac windows) 来运行具有 mac 和 windows 分支的工作流程。在此期间，您可能需要使用如下所示的两个计划来设置您的配置文件：

plan mac {
  reach goal_task via (Profile: debug) * (Os: mac)
}

plan win {
  reach goal_task via (Profile: debug) * (Os: windows)
}

值

工作流程中有几种类型的值

# literal values without spaces can be unquoted:
unquoted_var=literal_value_with_no_spaces
unquoted_var2=/literals/can/also/be/paths

# literal values can be written in double quotes
sentence="put a whole sentence in double quotes"

# values can refer to other values:
renamed=$unquoted_var

# interpolate variables in double quotes:
interpolated="the sentence above is: $sentence"

# the path to a task output can be specified with '@'.
# this variable contains the path to the output file "output_var_name" from the task "task_name":
task_output=$output_var_name@task_name

# values can be *branched* with parentheses.
# this variable has value "brew" on branch (Os: mac), "choco" on branch (Os: windows), etc.:
pkg_mgr=(Os: mac=brew windows=choco ubuntu=apt-get)

# when we want to create a value with the same name as a branchpoint, we can omit the value name.
# this assignment is shorthand for profile=(Debug: debug=debug release=release):
profile=(Debug: debug release)

# another example of a branched value using shorthand notation:
os=(Os: mac windows ubuntu)

# a value evaluated for a specific branch (a "branch graft") can be specified with brackets.
# this variable has the value of the variable "profile" on branch (Profile: release),
# regardless of which branch is currently being evaluated:
grafted=$profile[Profile: release]

# branch grafts can be combined with task outputs:
task_output_release=$output_var_name@task_name[Profile: release]

全局配置

可以在 global 块中指定值，每个值一行

global {
  var1="hi there"
  var2=$output@some_task
}

然后这些值就可以在工作流程中的任何任务中使用。

任务

任务包含工作流程文件中的大部分逻辑。它们看起来像这样

task cargo_build
  @cargo
  > lib="target/$profile/myrustlib"
  :: release_flag=(Profile: debug="" release="--release")
{
  cargo build $release_flag
}

这告诉 hr 创建一个任务

• 在 cargo 模块目录中运行（模块将在下面解释）
• 生成一个名为 lib 的输出，该输出由 hr 所知，并位于 target/$profile/myrustlib（将评估为 target/debug/myrustlib 或 target/release/myrustlib），具体取决于我们正在评估的分支：(Profile: debug) 或 (Profile: release)）。
• 接受一个名为 release_flag 的参数，该参数的值取决于我们是否在 (Profile: debug) 或 (Profile: release) 环境下。
• 运行命令 cargo build $release_flag。

在花括号之前的内容被称为 任务头。任务头包含一个名称以及一个可选的值列表，用于定义任务如何运行及其与其他任务的关系。这些值可以是以下任何一种：

• 任意数量的输入文件，使用 < 指定（如上所示未展示）。
• 任意数量的输出文件，使用 > 指定。
• 任意数量的参数，使用 :: 指定。
• 零个或一个模块定义，使用 @ 指定。

在任务头中定义的任何输入、输出和参数的变量名都对下面的代码块可用（参见上面的代码中如何使用 $release_flag）。

这些值（除模块外）使用上述相同的值语法，例如

< input=(Branched: branch1=val1 branch2=val2)
> output1=$config_var_defined_in_a_global_block
> output2="put/$variable_interpolation/in/double-quotes"
:: param1=$grafted_variable[Branchpoint: branch1]

可以定义多个同一类型的任务值，使用空格分隔的列表

< input1=foo input2=bar

并且在单行上可以定义多个这样的列表

< input1=foo input2=bar > output=output :: param1=x param2=y

此外，任务值中还有一些在全局块中不可用的缩写。任何未使用等号定义的输入或输出值

< input
> output

将被解释为

< input=input
> output=output

这在你例如不在乎输出文件的名称，只要它存在的情况下很有用。

参数可以使用 @ 符号指定，例如

param=@

这告诉 workflow 在全局块中查找名为 param 的变量，并使用其值。还有一些其他快捷方式在这里没有涉及，请参阅示例目录以获取更多信息。

输入（<）

任务输入是文件，它们与其他任务值的主要区别在于在任务运行之前会检查它们的存在。如果在任务运行之前任务定义的任何输入文件不存在，则执行停止。workflow 不关心它们是文件还是目录，只要它们存在即可。

与其他值一样，它们可以进行分支或合并。

输出（>）

任务的输出是文件，它们与其他任务值的不同之处在于，它们在任务运行之后才会进行存在性检查。如果任务定义的输出文件在任务运行后立即不存在，则认为任务失败，并停止执行。 workflow 不关心输出是文件还是目录，只要它们存在。与其他值一样，它们可以进行分支或嫁接。

输出应定义为相对路径，相对于任务代码将运行的目录（关于任务目录的更多信息稍后介绍）。

params (::

在任何时候都不会检查参数的存在性。可以将它们定义为文本字符串，或引用其他地方定义的配置值，但不能作为任务输出。

modules (@)

模块只是一个前面带有 @ 符号的单一标识符，例如 @cargo。为了使像 task cargo_build @cargo 这样的任务标题工作，必须在配置文件的其他地方定义一个名为 cargo 的模块，例如

module cargo=/home/me/code/my-crate

通常，对于未指定 @module 的任务，workflow 将为每个任务执行创建一个新的目录，并在其中运行其代码。所有输出都假定相对于此新目录，并且依赖它们的其他任务将期望在那里找到它们。

对于 @module 任务，workflow 将在模块目录中执行代码，然后从模块目录将输出文件复制回任务目录（其他任务可以找到它们）。

这主要用于构建命令，这些命令依赖于存在于特定位置且我们不一定希望每次运行工作流时都将其复制到新目录中的源代码。请参阅 examples 以获取示例。

使任务无效

-x 标志告诉 hr 使已运行的任务无效

> hr -x -t pkgbuild -b Framework=vst

上面的命令将使名为 pkgbuild 的任务对分支 (Framework: vst) 无效。这意味着下一次运行工作流时，将重新运行该任务，无论它是否成功。该任务的所有依赖任务也将重新运行，因为它们的输入现在被认为是无效的。

指定任务名称的 -t 标志始终是必需的，但指定分支的 -b 标志是可选的。如果省略，hr 将使任务在所有分支上的所有实现无效。

对于更复杂的分支，可以同时指定多个分支点，使用多个 -b 标志

> hr -x -t pkgbuild -b Framework=vst -b Profile=release

或者通过 + 连接它们

> hr -x -t pkgbuild -b Framework=vst+Profile=release