配置文件看起来像这样

> 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的子目录，在每个子目录中都有一个.txt文件，该文件是由运行配置文件中的bash代码创建的。

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

请注意，所有输出默认都写入到由 hr 调用的目录 output 下的 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）。
• 接受一个参数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

上面的操作将使分支 (Framework: vst) 上的任务 pkgbuild 失效。这意味着下次运行工作流时，将重新运行该任务，不管它是否成功。由于这些任务的输入现在被认为是无效的，所以所有依赖的任务也将重新运行。

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

对于更复杂的分支，可以一起指定多个分支点，可以是多个 -b 标志

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

或者通过 + 链接它们

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

路线图

完成以下大部分内容应使我们达到 1.0 版本的发布

• 更复杂的计划：多个目标节点、多个分支
• 提高测试覆盖率
• 更详细的错误信息
• 允许在配置文件中导入，以便可以将它们拆分到多个文件中
  • 在用户的家目录中创建全局设置文件
• 允许在配置中使用内置变量，例如 $HOME
• 允许在命令行中覆盖配置值
• 允许用户在命令行中验证工作流程而不执行它
• 允许用户使用命令行选项检查工作流程
• 扩展此文档
• 决定 hr 是否真的是一个好名字...

之后，我们可以考虑扩展基本功能

• 添加远程执行代码或在容器中执行代码的选项
• 使用多线程同时执行任务
• 引入跨任务重用通用代码的方法
• 与终端复用器交互？
• 添加更多富有表现力的语法，例如定义为范围的分支（N: 0..10）