Language:
Page Info
Engine Version:
Share

BuildGraph 脚本元素

BuildGraph 脚本以 XML 编写。此文档包含 BuildGraph 脚本中的数据类型以及其整体结构。

元素

元素描述它们包含的数据,使它们成为 BuildGraph 脚本的基础构建块之一。下表包含作为元数据提供的项目,将在构建系统上运行时导出。在本地执行任务时它们不会被 BuildGraph 直接使用,将以 [META] 标记。

图表结构

一个 BuildGraph 脚本通常由以下元素定义:

  • <Node>

  • <Aggregate>

  • <Agent>

  • <Trigger>

节点

<Node> 是 BuildGraph 中执行的最小单位,拥有一套输入和输出。每个 <Node> 由按顺序执行的一个任务序列组成。

属性

类型

是否必需?

描述

Name

命名

必需

节点名。

Requires

目标列表

可选

由此节点需要执行的其他节点生成的节点列表、聚合,或标记文件集,由分号间隔。

Produces

标记列表

可选

此节点向其他节点提供的标记文件集,由分号间隔。

After

目标列表

可选

在此节点之前运行的节点列表,如他们为当前目标的部分(如非当前目标的部分,则无视)。由分号间隔。

NotifyOnWarnings

布尔

可选

如为 false,此节点将不生成警告通知。只由构建系统使用。默认为 true[META]

If

条件

可选

将被求值的条件。元素将被无视,除非条件求值为 true

聚合

<Aggregate> 声明一个命名聚合,可用作一套其他节点(或生成的标签集)的同义词。

属性

类型

是否必需?

描述

Name

命名

必需

聚合名。

Requires

目标列表

必需

此聚合的依赖性列表。可能是节点、标记的文件集,或代理群组。

If

条件

可选

将被求值的条件。元素将被无视,除非条件求值为 true

代理

<Agent> 定义按次序执行的节点上代理的要求(无需清理中间目录)。本地构建时将无视 <Agent> 要求,但必须被指定。

属性

类型

是否必需?

描述

Name

命名

必需

群组名。

Type

辨识符列表

可选

运行的代理类型。此字符串的含义由 host 构建系统所推断;它不含任何本质含义。[META]

If

条件

可选

将被求值的条件。元素将被无视,除非条件求值为 true

触发

<Trigger> 的作用是图表部分(该图表只在显式用户介入后执行)的一个容器。如需在触发后执行节点,将 -Trigger=<Name> 传至命令行。

属性

类型

是否必需?

描述

Name

命名

必需

触发名。

If

条件

可选

将被求值的条件。元素将被无视,除非条件求值为 true

属性操作

BuildGraph 属性可通过以下元素进行修改:

  • <Property>

  • <Option>

  • <EnvVar>

属性

<Property> 设置属性的数值。如外部作用域中的属性已使用相同命名声明,<Property> 会将其覆盖。否则将在当前作用域中声明一个新属性。

属性

类型

是否必需?

描述

Name

命名

必需

设置的属性名。

Value

字符串

必需

属性的新值。

If

条件

可选

将被求值的条件。元素将被无视,除非条件求值为 true

选项

<Option> 定义可从命令行进行设置的用户选项。<Option> 可能只出现在全局作用域。

属性

类型

是否必需?

描述

Name

命名

必需

通过选项数值初始化的选项(和属性)名。

Description

字符串

必需

通过 -ListOnly 参数运行 BuildGraph 时选项显示的描述。

Restrict

正则表达式

可选

匹配此选项有效数值的正则表达式(如 [a-zA-Z]+, true | false)。

DefaultValue

字符串

必需

用户不进行显式设置时的选项默认值。

If

条件

可选

将被求值的条件。元素将被无视,除非条件求值为 true

EnvVar

<EnvVar> 声明属性,以包含环境变量的内容(如未设置则为空白字符串)。 <EnvVar> 可能只出现在全局作用域。

属性

类型

是否必需?

描述

Name

Name

Required

作为属性引入的环境变量名。

If

条件

可选

将被求值的条件。元素将被无视,除非条件求值为 true

流动控制

可通过以下元素控制 BuildGraph 脚本的流动。

  • <Include>

  • <Do>

  • <Switch>

  • <ForEach>

包括

<Include> 处理其他 BuildGraph 脚本的内容,就像它存在出现在此文件中那样。<Include> 可能只出现在全局作用域。

属性

类型

是否必需?

描述

Script

字符串

必需

需要包含的脚本的路径(相对于当前脚本)。

If

条件

可选

将被求值的条件。元素将被无视,除非条件求值为 true

Do

<Do> 将元素的序列分组,仅在条件求值为 true 时对它们进行处理。

属性

类型

是否必需?

描述

If

条件

可选

将被求值的条件。元素将被无视,除非条件求值为 true

切换

<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

条件

可选

将被求值的条件。元素将被无视,除非条件求值为 true

ForEach

<ForEach> 通过在一个列表中指定到每个项目的给定属性(由分号间隔)来展开元素主体。

<ForEach> 语句示例:

<ForEach Name="Counter" Values="1;2;3;4;5">
    <Log Message="Counter=$(Counter)"/>
</ForEach>

属性

类型

是否必需?

描述

Name

命名

必需

指定到列表中每个数值的属性。

Values

字符串列表

必需

数值列表,由分号间隔。

If

条件

可选

将被求值的条件。元素将被无视,除非条件求值为 true

诊断

可通过以下元素对 BuildGraph 脚本执行诊断。

  • <Warning>

  • <Error>

警告

<Warning> 会在执行图表前输出警告消息。可能包含在节点、代理、触发、或整体作用域中。如` 在被裁剪到被执行的目标后仍为图表的一部分,它将只提供一个输出。

属性

类型

是否必需?

描述

Message

字符串

必需

被打印到日志的文本。

If

条件

可选

将被求值的条件。元素将被无视,除非条件求值为 true

错误

<Error> 将输出错误消息。<Error> 可能包含在节点、代理、触发、或整体作用域中。如 <Error> 在被裁剪到被执行的目标后仍为图表的一部分,它将只提供一个输出。

属性

类型

是否必需?

描述

Message

字符串

必需

被打印到日志的文本。

If

条件

可选

将被求值的条件。元素将被无视,除非条件求值为 true