请注意，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 （其值将取决于我们正在评估的分支：(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 不关心输出是文件还是目录，只关心它们是否存在。并且，与其他值一样，它们可以进行分支或嫁接。

输出应定义为相对路径，相对于任务代码运行时的目录（稍后详细介绍任务目录）。

参数 (::)

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

模块 (@)

模块只是一个以 @ 符号开头的单个标识符，例如 @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