请注意，hr在每个任务目录中创建了一些额外的文件

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

重新运行heron-rebuild

每次调用hr时，它都会检查输出目录中已完成的任务，如果可以，则使用它们的输出而不重新运行它们。如果任务在工作流程执行过程中失败，整个工作流程执行将停止，但任何成功的任务仍然可以重用。此时，您可以纠正错误，再次调用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 不关心它们是文件还是目录，只要它们存在即可。

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

输出（>）

任务的输出是文件，它们与其他任务值的不同之处在于，在任务运行后会对它们的存续性进行检查。如果一个任务定义的输出文件在任务运行后立即不存在，则认为任务执行失败，执行停止。《code>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）