INTSourceChangelist:3356804
Availability: Public
Title: BuildGraph 스크립트 엘리먼트
Crumbs:
Description:BuildGraph 의 엘리먼트에 대해 알아봅니다.
version: 4.13
parent:Programming/Development/BuildGraph
type:Reference
tags:Programming
tags:BuildGraph

[VAR:TopicCompact]
[OBJECT:TopicCompact]
	[PARAM:image]
		![%Programming/Development/BuildGraph/ScriptAnatomy/Elements%](elements_topic.png)
	[/PARAM]
	[PARAM:icon]
		![](%ROOT%/reference_icon.png)(convert:false)
	[/PARAM]
	[PARAM:title]
		%Programming/Development/BuildGraph/ScriptAnatomy/Elements:title%
	[/PARAM]
	[PARAM:description]
		%Programming/Development/BuildGraph/ScriptAnatomy/Elements:description%
	[/PARAM]
	[PARAM:path]
		[RELATIVE:Programming/Development/BuildGraph/ScriptAnatomy/Elements]
	[/PARAM]
[/OBJECT]
[/VAR]

[TOC(start:1 end:2)]

[EXCERPT:BuildGraphScriptElements]

BuildGraph 스크립트는 XML 로 작성합니다. 여기서는 BuildGraph 스크립트에서 찾을 수 있는 데이터 유형과 아울러 전체적인 구조체에 대해 알아봅니다.

## 엘리먼트

엘리먼트(element)는 그 안에 포함된 데이터의 설명으로, BuildGraph 스크립트의 기본 구성 요소 중 하나입니다. 
다음 표는 메타데이터로 제공되는 항목으로, 빌드 시스템에서 실행할 때 익스포트되는 것입니다. 
로컬에서 태스크를 실행할 때 BuildGraph 에 직접 사용되지는 않지만, `[META]` 태그가 붙습니다.

## 그래프 구조체

BuildGraph 스크립트는 보통 다음 엘리먼트로 정의됩니다:

* `<Node>` 노드
* `<Aggregate>` 어그리게이트
* `<Agent>` 에이전트
* `<Trigger>` 트리거

### 노드

`<Node>` 노드는 BuildGraph 의 가장 작은 실행 단위로, 입력과 출력 세트를 갖습니다. 각 `<Node>` 는 
순서대로 실행되는 태스크 시퀀스로 이루어집니다.

| 어트리뷰트 | 유형 | 필수 | 설명 |
| ---------------- | ------------ | ------------ | ---------------- |
| Name | Name | 필수 | 노드 이름입니다. |
| Requires | Target List | 옵션 | 다른 노드에서 만들어진 노드, 어그리게이트, 태그 붙은 파일 세트의 세미콜론 구분 목록으로, 이 노드의 실행에 필요합니다. |
| Produces | Tag List | 옵션 | 이 노드가 다른 노드에 사용할 수 있도록 만든 태그 붙은 파일 세트를 세미콜론으로 구분한 것입니다. |
| After | Target List | 옵션 | 이 노드가 다음에 실행시켜야 하는 노드 목록으로, 현재 대상의 일부인 경우에만 실행합니다 (아니면 무시합니다). 세미콜론으로 구분합니다. |
| NotifyOnWarnings | Boolean | 옵션 | false 면 이 노드는 경고시 알림 신호를 냅니다. 빌드 시스템에만 사용됩니다. 기본값은 `true` 입니다. `[META]` |
| If | Condition | 옵션 | 평가할 조건입니다. 조건 평가가 `true` 로 나오지 않는 한 엘리먼트는 무시됩니다. |

### 어그리게이트

`<Aggregate>` 는 다른 노드의 세트 (또는 생성된 태그 세트)에 대한 동의어로 사용될 수 있는 네임드 어그리게이트를 선언합니다.

| 어트리뷰트 | 유형 | 필수 | 설명 | |
| ---------------- | ------------ | ------------ | -------------- |
| Name | Name | 필수 | 어그리게이트 이름입니다. |
| Requires | Target List | 필수 | 이 어그리게이트의 종속성 목록입니다. 노드, 태그 붙은 파일 세트, 에이전트 그룹이 될 수 있습니다. |
| If | Condition | 옵션 | 평가할 조건입니다. 조건이 `true` 로 평가되지 않는 한 엘리먼트는 무시됩니다. |

### 에이전트

`<Agent>` 는 (중간 디렉터리를 지우지 않고) 시퀀스로 실행될 노드의 에이전트 요건을 정의합니다.
`<Agent>` 요건은 로컬에서 빌드할 때는 무시되지만, 반드시 지정해야 합니다.

| 어트리뷰트 | 유형 | 필수? | 설명 |
| ---------------- | --------------- | ------------ | ----------- |
| Name | Name | 필수 | 그룹 이름입니다. |
| Type | Identifier List | 옵션 | 에이전트를 실행시킬 유형입니다. 이 스트링의 뜻은 호스트 빌드 시스템이 추론하며, 고유 의미를 갖지는 않습니다. `[META]` |
| If | Condition | 옵션 | 평가할 조건입니다. 조건이 `true` 로 평가되지 않는 한 엘리먼트는 무시됩니다. |

### 트리거

`<Trigger>` 는 사용자 직접 개입으로만 실행시켜야 하는 그래프 부분에 대한 컨테이너 역할을 합니다. 
트리거 이후 노드를 실행하려면, 명령줄에 `-Trigger=<Name>` 을 전달합니다.

| 어트리뷰트 | 유형 | 필수? | 설명 |
| ---------------- | --------------- | ------------ | ------------------ |
| Name | Name | 필수 | 트리거 이름입니다. |
| If | Condition | 옵션 | 평가할 조건입니다. 조건이 `true` 로 평가되지 않는 한 엘리먼트는 무시됩니다. |

## 프로퍼티 조작

BuildGraph 프로퍼티는 다음 엘리먼트로 변경할 수 있습니다:

* `<Property>` 프로퍼티
* `<Option>` 옵션
* `<EnvVar>` 환경변수

### 프로퍼티

`<Property>` 는 프로퍼티의 값을 설정합니다. 외부 영역의 프로퍼티가 이미 같은 이름으로 선언된 경우,
`<Property>` 로 덮어씁니다. 그렇지 않은 경우, 현재 영역에 새로운 프로퍼티를 선언합니다.

| 어트리뷰트 | 유형 | 필수? | 설명 |
| ---------------- | ---------- | -------- | -------------- |
| Name | Name | 필수 | 설정할 프로퍼티 이름입니다. |
| Value | String | 필수 | 프로퍼티에 대한 새 값입니다. |
| If | Condition | 옵션 | 평가할 조건입니다. 조건이 `true` 로 평가되지 않는 한 엘리먼트는 무시됩니다. |

### 옵션

`<Option>` 은 명령줄에서 설정할 수 있는 사용자 옵션을 정의합니다. `<Option>` 은 전체 영역에서만 나타날 수 있습니다.

| 어트리뷰트 | 유형 | 필수? | 설명 |
| ------------ | --------- | ------------ | ------------- |
| Name | Name | 필수 | 옵션의 값으로 초기화시킬 옵션(과 프로퍼티) 이름입니다. |
| Description | String | 필수 | BuildGraph 에 -ListOnly 인수를 붙여 실행하면 표시되는 옵션에 대한 설명입니다. |
| Restrict | Regex | 옵션 | 이 옵션의 유효 값에 일치하는 정규표현식입니다 (예: `[a-zA-Z]+`, `true | false`). |
| DefaultValue | String | 필수 | 사용자가 명시적으로 설정하지 않은 경우의 옵션 기본값입니다. |
| If | Condition | 옵션 | 평가할 조건입니다. 조건이 `true` 로 평가되지 않는 한 엘리먼트는 무시됩니다. |

### 환경변수

`<EnvVar>` 는 환경 변수의 내용( 또는 설정되지 않은 경우 공백 스트링)을 담는 프로퍼티를 선언합니다.
`<EnvVar>` 는 전체 영역에서만 나타납니다.

| 어트리뷰트 | 유형 | 필수? | 설명 |
| ------------ | --------- | ------------ | ------------- |
| Name | Name | 필수 | 프로퍼티로 도입할 환경 변수 이름입니다. |
| If | Condition | 옵션 | 평가할 조건입니다. 조건이 `true` 로 평가되지 않는 한 엘리먼트는 무시됩니다. |

## 흐름 제어

BuildGraph 스크립트의 흐름을 제어할 수 있는 엘리먼트는 다음과 같습니다:

* `<Include>`
* `<Do>`
* `<Switch>`
* `<ForEach>`

### Include

`<Include>` 는 다른 BuildGraph 스크립트의 내용을 이 파일 안에 나타난 것처럼 처리합니다.
`<Include>` 는 전체 영역에서만 나타날 수 있습니다.

| 어트리뷰트 | 유형 | 필수? | 설명 |
| ------------ | --------- | ------------ | ------------- |
| Script | String | 필수 | 포함시키고자 하는 스크립트로의 (현재 스크립트 기준 상대) 경로입니다. |
| If | Condition | 옵션 | 평가할 조건입니다. 조건이 `true` 로 평가되지 않는 한 엘리먼트는 무시됩니다. |

### Do

`<Do>` 는 엘리먼트 시퀀스를 그룹으로 묶어 조건이 true 로 평가되는 경우에만 처리합니다.

| 어트리뷰트 | 유형 | 필수? | 설명 |
| ------------ | --------- | ------------ | ------------- |
| If | Condition | 옵션 | 평가할 조건입니다. 조건이 `true` 로 평가되지 않는 한 엘리먼트는 무시됩니다. |

### Switch

`<Switch>` 는 [C](http://www.open-std.org/jtc1/sc22/wg14/www/standards) 의 switch 문과 비슷한데, 
브랜치의 시퀀스에 있는 조건을 평가하고, true 로 평가되는 조건이 있는 첫 번째 문을 처리합니다.

예제 `<Switch>` 문:

	<Switch>
		<Case If=X>
			<Elements go here>
		</Case>
		<Case If=Y>
			<Elements go here>
		</Case>
		<Default>
			<Elements go here>
		</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>` 은 실행중인 대상으로 추려낸(trim down) 이후에도 그래프의 일부인 경우에만 
출력을 제공할 것입니다.

| 어트리뷰트 | 유형 | 필수? | 설명 |
| ------------ | --------- | ------------ | ------------- |
| Message | String | 필수 | 로그에 출력할 텍스트입니다. |
| If | Condition | 옵션 | 평가할 조건입니다. 조건이 `true` 로 평가되지 않는 한 엘리먼트는 무시됩니다. |

### 오류

`<Error>` 는 오류 메시지를 출력합니다. `<Error>` 는 노드, 에이전트, 트리거, 전체 영역에 포함시킬 수 있습니다.
`<Error>` 는 실행중인 대상으로 추려낸(trim down) 이후에도 그래프의 일부인 경우에만 출력을 제공할 것입니다.

| 어트리뷰트 | 유형 | 필수? | 설명 |
| ------------ | --------- | ------------ | ------------- |
| Message | String | 필수 | 로그에 출력할 텍스트입니다. |
| If | Condition | 옵션 | 평가할 조건입니다. 조건이 `true` 로 평가되지 않는 한 엘리먼트는 무시됩니다. |

[/EXCERPT:BuildGraphScriptElements]

[EXCERPT:BuildGraphScriptTasks]
### 태스크

보통 프로젝트 전용 유틸리티 스크립트는 AutomationTool BuildCommand 클래스로 구현됩니다. 하지만 프로젝트에 대해 커스텀 태스크를 
자동화시키고자 할 때가 있습니다. 그럴 때 BuildGraph 가 도움이 됩니다. BuildGraph 는 태스크를 몇 개든 확장할 수 있어, 요구에 딱 맞도록 
빌드 자동화 태스크를 커스터마이징할 수 있습니다. 다음 섹션에서는 BuildGraph 를 사용하여 커스텀 태스크를 
만드는 방법과 아울러, 커스텀 태스크 생성을 시작하기에 좋은 미리지정 태스크 목록에 대해서도 살펴보겠습니다.

## 커스텀 태스크

커스텀 태스크를 새로 만들기 위해서는, `CustomTask` 클래스에서 파생 클래스를 구현한 뒤 `[TaskElement]` 어트리뷰트를 적용하면 됩니다.
`TaskElement` 생성자는 인수를 둘 받습니다. 하나는 그것을 나타내는 XML 엘리먼트의 이름, 
다른 하나는 그 (로드 시간에 생성자에 전달되는) 파라미터가 들어있는 클래스 유형입니다 

XML 파일에서 파라미터 클래스 필드를 읽고자 하는 경우, `[TaskParameter]` 어트리뷰트를 태스크에 붙입니다. 
`TaskParameter` 어트리뷰트를 붙인다는 것은 파라미터가 필수인지 옵션인지, 인수에 적용시킬 
부가 인증(validation)을 포함해서 나타냅니다.

## 미리정의된 태스크

태스크 생성을 위한 시작 지점이 있었으면 하시는 분들을 위해, 미리정의된 태스크 다수를 템플릿으로 제공해 드리고 있습니다.
시작 지점으로 쓸 단순한 미리정의된 태스크를 찾으시는 경우, `LogTask` 에서부터 시작해 보실 것을 추천합니다. BuildGraph 최신 변경사항을 계속 받아보시려면, 이 글을 즐겨찾기 등록해 주세요.
주기적으로 다음 미리정의된 태스크 목록을 업데이트하겠습니다.

[INCLUDE:Programming/Development/BuildGraph/ScriptAnatomy/Tasks/PredefinedTasks]

[/EXCERPT:BuildGraphScriptTasks]