BuildGraph スクリプトは XML で記述されます。このドキュメントでは、BuildGraph スクリプト内にあるデータの種類と全体的な構造について説明します。
エレメント
エレメント は、そこに含まれるデータを表し、BuildGraph スクリプトの基本的な構成要素になります。以下の表には、メタデータとして提供され、ビルド システムで実行するとエクスポートされるアイテムがあります。BuildGraph によって直接使用されなくても、これらはローカルでタスクを実行するときに [META]
とタグ付けされます。
グラフ構造
BuildGraph スクリプトは、通常以下のエレメントで定義されます。
-
<Node>
-
<Aggregate>
-
<Agent>
-
<Trigger>
Node
<Node>
は、入力と出力のセットを持つ BuildGraph の最小実行単位です。各 <Node>
は、順番に実行されるタスクのシーケンスで構成されます。
属性 | 型 | 必須? | 説明 |
---|---|---|---|
Name | Name | 必須 | ノード名。 |
Requires | Target List | オプション | このノードが実行する必要がある他のノードによって生成されたノード、集成体 (aggregate)、タグ付けしたファイル。セミコロンで区切られます。 |
Produces | Tag List | オプション | このノードが他のノードに対して利用可能にするタグ付けされたファイル セット。セミコロンで区切られます。 |
After | Target List | オプション | カレント ターゲットの一部である場合 (そうでない場合は無視)、このノードがその後で実行すべきノードのリスト。セミコロンで区切られます。 |
NotifyOnWarnings | Boolean | オプション | false の場合、このノードは警告の通知を生成しません。ビルド システムのみが使用します。デフォルトで true 。[META] |
If | Condition | オプション | 評価する条件式。条件式の結果が true でなければ、そのエレメントは無視されます。 |
Aggregate
<Aggregate>
は、生成されたタグセットまたは他のノードのセットの同義として使用可能な名前付きの aggregate を宣言します。
属性 | 型 | 必須? | 説明 |
---|---|---|---|
Name | Name | 必須? | aggregate の名前 |
Requires | Target List | 必須 | aggregate の依存関係のリスト。ノード、タグ付けしたファイル セット、agent のグループなどがあります。 |
If | Condition | オプション | 評価する条件式。条件式の結果が true でなければ、そのエレメントは無視されます。 |
Agent
<Agent>
は、シーケンスで実行される (中間ディレクトリをクリーニングせずに) ノードのエージェントの要件を定義します。 ローカルでビルドする場合、<Agent>
の要件は無視されますが、指定しなければなりません。
属性 | 型 | 必須? | 説明 |
---|---|---|---|
Name | Name | 必須 | グループの名前 |
Type | Identifier List | オプション | 実行する agent のタイプ。この文字列の意味は、ホストのビルド システムによって推測されます。固有の意味は持ちません。[META] |
If | Condition | オプション | 評価する条件式。条件式の結果が true でなければ、そのエレメントは無視されます。 |
Trigger
<Trigger>
は、グラフの一部のコンテナの役割を果たします。ユーザーが明示的に操作する場合に限り実行されます。トリガーの後にノードを実行するには、 -Trigger=<Name>
をコマンドラインに渡します。
属性 | 型 | 必須? | 説明 |
---|---|---|---|
Name | Name | 必須 | トリガーの名前 |
If | Condition | オプション | 評価する条件式。条件式の結果が true でなければ、そのエレメントは無視されます。 |
プロパティの操作
BuildGraph のプロパティは、以下のエレメントで修正することができます。
-
<Property>
-
<Option>
-
<EnvVar>
Property
<Property>
は、プロパティの値を設定します。外部のスコープにあるプロパティが既に同じ名前で宣言されている場合、<Property>
がそれを上書きします。それ以外の場合はカレント スコープで新しいプロパティが宣言されます。
属性 | 型 | 必須? | 説明 |
---|---|---|---|
Name | Name | 必須 | 設定するプロパティの名前 |
Value | String | 必須 | プロパティの新しい値 |
If | Condition | オプション | 評価する条件式。条件式の結果が true でなければ、そのエレメントは無視されます。 |
Option
<Option>
は、コマンドラインから設定可能なユーザー オプションを定義します。 <Option>
はグローバル スコープでのみ表示されます。
属性 | 型 | 必須? | 説明 |
---|---|---|---|
Name | Name | 必須 | オプションの値で初期化するオプション名 (およびプロパティ)。 |
Description | String | 必須 | -ListOnly 引数で BuildGraph を実行する場合に表示するオプションの説明。 |
Restrict | Regex | オプション | このオプションに対して有効な値にマッチする Regex (例、 [a-zA-Z]+ , true |false )。 |
DefaultValue | String | 必須 | ユーザーが明示的に設定しない場合のこのオプションのデフォルト値。 |
If | Condition | オプション | 評価する条件式。条件式の結果が true でなければ、そのエレメントは無視されます。 |
EnvVar
<EnvVar>
は、環境変数のコンテンツを含めるプロパティを宣言します (または設定されていない場合は空の文字列)。 <EnvVar>
はグローバル スコープでのみ表示されることがあります。
属性 | 型 | 必須? | 説明 |
---|---|---|---|
Name | Name | 必須 | プロパティとして導入する環境変数名。 |
If | Condition | オプション | 評価する条件式。条件式の結果が true でなければ、そのエレメントは無視されます。 |
Flow Control
以下のエレメントで BuildGraph スクリプトのフローを制御することができます。
-
<Include>
-
<Do>
-
<Switch>
-
<ForEach>
Include
<Include>
は、別の BuildGraph スクリプトのコンテンツをこのファイル内で表示されているかのように処理します。 <Include>
はグローバル スコープでのみ表示されることがあります。
属性 | 型 | 必須? | 説明 |
---|---|---|---|
Script | String | 必須 | インクルードしたいスクリプトへのパス (カレント スクリプトに相対的) |
If | Condition | オプション | 評価する条件式。条件式の結果が true でなければ、そのエレメントは無視されます。 |
Do
<Do>
はエレメントのシーケンスをグループ化し、条件式の結果が true の場合のみこうしたものを処理します。
属性 | 型 | 必須? | 説明 |
---|---|---|---|
If | Condition | オプション | 評価する条件式。条件式の結果が true でなければ、そのエレメントは無視されます。 |
Switch
<Switch>
は C の switch 文に類似しています。ブランチのシーケンスの条件を評価し、結果が true になった最初の文を処理するからです。
<Switch>
文の例:
<Switch>
<Case If=X>
<Elements go here if X is true>
</Case>
<Case If=Y>
<Elements go here if X is false but Y is true>
</Case>
<Default>
<Elements go here otherwise>
</Default>
</Switch>
属性 | 型 | 必須? | 説明 |
---|---|---|---|
If | Condition | オプション | 評価する条件式。条件式の結果が true でなければ、そのエレメントは無視されます。 |
ForEach
<ForEach>
は、エレメントのボディを、セミコロンで区切られるリストの各アイテムに割り当てられた任意のプロパティで展開します。
<ForEach>
文の例:
<ForEach Name="Counter" Values="1;2;3;4;5">
<Log Message="Counter=$(Counter)"/>
</ForEach>
属性 | 型 | 必須? | 説明 |
---|---|---|---|
Name | Name | 必須 | リストの各値に割り当てるプロパティ。 |
Values | String List | 必須 | セミコロンで区切られる値のリスト。 |
If | Condition | オプション | 評価する条件式。条件式の結果が true でなければ、そのエレメントは無視されます。 |
診断
以下のエレメントで BuildGraph スクリプトの診断を行うことができます、
-
<Warning>
-
<Error>
Warning
<Warning>
はグラフ実行前に警告メッセージを出力します。<Warning>
は、node、 agent、 trigger またはグローバル スコープに含まれる場合があります。<Warning>
は実行されているターゲットにトリムされた後、 まだグラフの一部である場合に出力します。
属性 | 型 | 必須? | 説明 |
---|---|---|---|
Message | String | 必須 | ログに出力するテキストです。 |
If | Condition | オプション | 評価する条件式。条件式の結果が true でなければ、そのエレメントは無視されます。 |
Error
<Error>
はエラー メッセージを出力します <Error>
node、 agent、 trigger またはグローバル スコープに含まれる場合があります。<Error>
は、実行されているターゲットにトリムされた後、まだグラフの一部であれば出力します。
属性 | 型 | 必須? | 説明 |
---|---|---|---|
Message | String | 必須 | ログに出力するテキストです。 |
If | Condition | オプション | 評価する条件式。条件式の結果が true でなければ、そのエレメントは無視されます。 |