Choose your operating system:
Windows
macOS
Linux
BuildGraph 脚本使用XML编写。本文档覆盖了 BuildGraph 脚本中的数据类型以及它们的整体结构。
元素
元素描述它们包含的数据,使它们成为 BuildGraph 脚本的基础构建块之一。下表包含作为元数据提供的项目,将在构建系统上运行时导出。在本地执行任务时它们不会被 BuildGraph 直接使用,将以 [META]
标记。
图表结构
一个 BuildGraph 脚本通常由以下元素定义:
<Node>
<Aggregate>
<Agent>
<Trigger>
节点
<Node>
是 BuildGraph 中执行的最小单位,拥有一套输入和输出。每个 <Node>
由按顺序执行的一个任务序列组成。
属性 |
类型 |
是否必需? |
描述 |
---|---|---|---|
Name |
命名 |
必需 |
节点名。 |
Requires |
目标列表 |
可选 |
由此节点需要执行的其他节点生成的节点列表、聚合,或标记文件集,由分号间隔。 |
Produces |
标记列表 |
可选 |
此节点向其他节点提供的标记文件集,由分号间隔。 |
After |
目标列表 |
可选 |
在此节点之前运行的节点列表,如他们为当前目标的部分(如非当前目标的部分,则无视)。由分号间隔。 |
NotifyOnWarnings |
布尔 |
可选 |
如为 false,此节点将不生成警告通知。只由构建系统使用。默认为 |
If |
条件 |
可选 |
将被求值的条件。元素将被无视,除非条件求值为 |
聚合
<Aggregate>
声明一个命名聚合,可用作一套其他节点(或生成的标签集)的同义词。
属性 |
类型 |
是否必需? |
描述 |
---|---|---|---|
Name |
命名 |
必需 |
聚合名。 |
Requires |
目标列表 |
必需 |
此聚合的依赖性列表。可能是节点、标记的文件集,或代理群组。 |
If |
条件 |
可选 |
将被求值的条件。元素将被无视,除非条件求值为 |
代理
<Agent>
定义按次序执行的节点上代理的要求(无需清理中间目录)。本地构建时将无视 <Agent>
要求,但必须被指定。
属性 |
类型 |
是否必需? |
描述 |
---|---|---|---|
Name |
命名 |
必需 |
群组名。 |
Type |
辨识符列表 |
可选 |
运行的代理类型。此字符串的含义由 host 构建系统所推断;它不含任何本质含义。 |
If |
条件 |
可选 |
将被求值的条件。元素将被无视,除非条件求值为 |
触发
<Trigger>
的作用是图表部分(该图表只在显式用户介入后执行)的一个容器。如需在触发后执行节点,将 -Trigger=<Name>
传至命令行。
属性 |
类型 |
是否必需? |
描述 |
---|---|---|---|
Name |
命名 |
必需 |
触发名。 |
If |
条件 |
可选 |
将被求值的条件。元素将被无视,除非条件求值为 |
属性操作
BuildGraph 属性可通过以下元素进行修改:
<Property>
<Option>
<EnvVar>
属性
<Property>
设置属性的数值。如外部作用域中的属性已使用相同命名声明,<Property>
会将其覆盖。否则将在当前作用域中声明一个新属性。
属性 |
类型 |
是否必需? |
描述 |
---|---|---|---|
Name |
命名 |
必需 |
设置的属性名。 |
Value |
字符串 |
必需 |
属性的新值。 |
If |
条件 |
可选 |
将被求值的条件。元素将被无视,除非条件求值为 |
选项
<Option>
定义可从命令行进行设置的用户选项。<Option>
可能只出现在全局作用域。
属性 |
类型 |
是否必需? |
描述 |
---|---|---|---|
Name |
命名 |
必需 |
通过选项数值初始化的选项(和属性)名。 |
Description |
字符串 |
必需 |
通过 -ListOnly 参数运行 BuildGraph 时选项显示的描述。 |
Restrict |
正则表达式 |
可选 |
匹配此选项有效数值的正则表达式(如 |
DefaultValue |
字符串 |
必需 |
用户不进行显式设置时的选项默认值。 |
If |
条件 |
可选 |
将被求值的条件。元素将被无视,除非条件求值为 |
EnvVar
<EnvVar>
声明属性,以包含环境变量的内容(如未设置则为空白字符串)。
<EnvVar>
可能只出现在全局作用域。
属性 |
类型 |
是否必需? |
描述 |
---|---|---|---|
Name |
Name |
Required |
作为属性引入的环境变量名。 |
If |
条件 |
可选 |
将被求值的条件。元素将被无视,除非条件求值为 |
流动控制
可通过以下元素控制 BuildGraph 脚本的流动。
<Include>
<Do>
<Switch>
<ForEach>
包括
<Include>
处理其他 BuildGraph 脚本的内容,就像它存在出现在此文件中那样。<Include>
可能只出现在全局作用域。
属性 |
类型 |
是否必需? |
描述 |
---|---|---|---|
Script |
字符串 |
必需 |
需要包含的脚本的路径(相对于当前脚本)。 |
If |
条件 |
可选 |
将被求值的条件。元素将被无视,除非条件求值为 |
Do
<Do>
将元素的序列分组,仅在条件求值为 true 时对它们进行处理。
属性 |
类型 |
是否必需? |
描述 |
---|---|---|---|
If |
条件 |
可选 |
将被求值的条件。元素将被无视,除非条件求值为 |
切换
<Switch>
与 C 切换语句相似,因其在分支序列上对条件求值,使用求值为 true 的条件处理首个语句。
<Switch>
语句示例:
<Switch>
<Case If=X>
<Elements go here>
</Case>
<Case If=Y>
<Elements go here>
</Case>
<Default>
<Elements go here>
</Default>
</Switch>
属性 |
类型 |
是否必需? |
描述 |
---|---|---|---|
If |
条件 |
可选 |
将被求值的条件。元素将被无视,除非条件求值为 |
ForEach
<ForEach>
通过在一个列表中指定到每个项目的给定属性(由分号间隔)来展开元素主体。
<ForEach>
语句示例:
<ForEach Name="Counter" Values="1;2;3;4;5">
<Log Message="Counter=$(Counter)"/>
</ForEach>
属性 |
类型 |
是否必需? |
描述 |
---|---|---|---|
Name |
命名 |
必需 |
指定到列表中每个数值的属性。 |
Values |
字符串列表 |
必需 |
数值列表,由分号间隔。 |
If |
条件 |
可选 |
将被求值的条件。元素将被无视,除非条件求值为 |
诊断
可通过以下元素对 BuildGraph 脚本执行诊断。
<Warning>
<Error>
警告
<Warning> 会在执行图表前输出警告消息。
可能包含在节点、代理、触发、或整体作用域中。如
属性 |
类型 |
是否必需? |
描述 |
---|---|---|---|
Message |
字符串 |
必需 |
被打印到日志的文本。 |
If |
条件 |
可选 |
将被求值的条件。元素将被无视,除非条件求值为 |
错误
<Error>
将输出错误消息。<Error>
可能包含在节点、代理、触发、或整体作用域中。如 <Error>
在被裁剪到被执行的目标后仍为图表的一部分,它将只提供一个输出。
属性 |
类型 |
是否必需? |
描述 |
---|---|---|---|
Message |
字符串 |
必需 |
被打印到日志的文本。 |
If |
条件 |
可选 |
将被求值的条件。元素将被无视,除非条件求值为 |