언리얼스크립트 전처리기 (UPP)

개요

Unreal Engine 3에서는 이제 UnrealScript 컴파일러가 전처리기를 지원합니다. 이 전처리기는 C++ 의 전처리기와 매우 비슷하게 작용하며, 매크로 를 통한 조건부 컴파일의 지원에 최적입니다.

기본

매크로의 처리가 UnrealScript의 컴파일에 앞서 행해집니다. 이것은 별도의 단계이므로 UnrealScript의 어휘 규정과는 연관되어 있지 않습니다 .

유효 범위

매크로는 파일 범위입니다. 이것은 스크립트 클래스 (.uc) 파일의 x째 줄에서 정의된 매크로는 그 파일의 x+n 줄에서만 (x째 줄 다음에서부터만) 유용하며, (다른 .uc 파일에 포함되지 않은 한) 다른 어느 파일에서도 유용하지 않다는 뜻입니다. 그렇지만 프로젝트의 루트 폴더에 Globals.uci 파일을 만들면 (즉 Development\Src\MyProject\Globals.uci), 그 패키지 내의 모든 클래스는 자동적으로 이곳의 매크로들을 이용할 수 있게 됩니다.

매크로의 사용

매크로를 불러오려면 그 이름의 앞에 ` (반대방향 따옴표)를 붙입니다. 따라서 파라미터를 가지고 있지 않은 hello 매크로를 확장하려면 다음과 같이 하면 됩니다:

`hello

마찬가지로, 다음에서처럼 따옴표 다음에 매크로의 이름을 { } 안에 넣어도 됩니다:

`{hello}

이것은 편의상 여백을 가지고 있지 않은 텍스트의 한가운데에 매크로의 확장을 “삽입” 하는 것을 가능하게 해줍니다:

hippo`{hello}potamus

그런데 hello 매크로가 어떻게 정의되었느냐구요? 내장 매크로인 define 은 C++의 define과 매우 흡사하게 작용합니다:

1. 키워드 `define, 그 다음에 적어도 하나의 여백 문자
2. 매크로의 이름(그리고 선택적으로 함수의 파라미터 목록), 그 다음에 적어도 하나의 여백 문자
3. 매크로 본체의 정의

따라서 hello 는 다음과 같이 정의됩니다:

`define   hello   "Hello, World!"

이제부터 `hello 는 "Hello, World!" (인용부호 포함)로 대체됩니다. 매크로 확장의 모든 결과는, 매크로를 확장할 기회가 있는지 보기 위해 다시 스캔됩니다. 매크로 확장은 이번에는 확장되는 매크로를 포함할 수 있습니다; 이는 "끝없이 재귀하는" 매크로가 작성될 수 있다는 것을 의미합니다.

"\n" 표기를 사용하여 매크로 확장에다 몇 줄을 새로 끼워넣어야 할 수도 있습니다. 이는 프리프로세서 매크로 디버깅에 좋기도 하며, DefaultProperties 에서 사용되는 매크로 작업에 필수적입니다. 예로:

`define EndComboBox(Name) \
    End Object \n\
    MenuObjects.Add(`Name)

매크로 파라미터

매크로의 파라미터는 매크로 이름 바로 뒤에 괄호 안에 콤마로 분리되는 목록으로서 표시되며, 위치적으로 전달됩니다. 목록의 열림 괄호가 반드시 매크로 이름의 바로 뒤에 와야 이 변수목록이 매크로 호출의 일부로서 인식됩니다. 매크로의 파라미터에 대한 상세한 내용은 내장 매크로 define 에 관한 아래의 설명 을 참고하십시오.

내장 매크로

define

`define <macroname>[<(paramA[,paramB...])>] [<macrodefinition>]

이름이 붙여진 매크로를 정의하여 주어진 내용대로 확장하도록 합니다. 매크로에 내용이 주어지지 않으면 매크로가 정의되기는 하지만 빈 문자열로 확장됩니다.

매크로의 파라미터들은 매크로 이름 바로 뒤에 타입이 없는 함수 파라미터의 목록에 명기됩니다. 매크로의 정의에서 파라미터들은 이름에 의해 참조되며 이름 앞에 반대방향 따옴표가 붙습니다. 예를 들면 다음과 같습니다:

`define DeclareInt(x) var int `x;

특별 매크로 `# 는 지정된 파라미터의 수를 나타내며, 매크로 정의 내에서만 참조될 수 있습니다.

if / else / endif

`if(< value >)
`else
`endif

이 세가지 매크로들은 함께 조건부 컴파일을 지원합니다. 파라미터 <value>가 처리되고, 만일 그것이 공백이 아닌 문자열로 확장되는 경우에는 if-점검은 true로 평가됩니다; 그렇지 않으면 false로 간주됩니다.

조건이 true인 경우에는 `if 와 `else (존재할 경우) 또는 `endif 사이에 있는 텍스트가 처리된 출력으로 내보내집니다; 조건이 true가 아닌 경우에는, 줄의 끝을 나타내는 문자만이 내보내집니다. 이렇게 함으로써 처리된 텍스트의 줄 번호가 원래 텍스트의 줄 번호와 일치하게 됩니다.

원래의 조건이 false인 경우에는 (선택적) `else 와 `endif 사이에 있는 텍스트가 내보내집니다.

내보내지지 않은 코드에 있는 매크로는 평가되지 않는다는 점을 유념하십시오(중첩 레벨을 추적하기 위해서만 처리되는 `if 그룹은 예외).

include

`include(<파일이름>)

현 위치에서 <파일이름&gt ; 파일의 텍스트를 포함합니다. 기본으로, <filename>은 게임 .ini 파일의 Editor.EditorEngine 섹션에 있는 EditPackagesInPath에 의해 지정된 디렉토리에 상대적입니다. 만일 파일이름만을 지정하면(즉, 디렉토리 없이), 현재 컴파일되고 있는 패키지의 클래스 디렉토리에 있는 include 파일만이 검색됩니다.

isdefined

`isdefined(< macroname >)
`notdefined(< macroname >)


정의에 상관없이 매크로가 정의된 경우(정의되지 않은 경우) 문자열 "1" 로 평가됩니다. 조건부 컴파일에 유용합니다.

undefine

`undefine(< macroname >)

< macroname >의 현재 정의를 제거합니다. (`cond, `txt, `#, 등) 매크로 파라미터 이름에 대해서는 작용하지 않습니다.

log / warn

`log(string OutputString, optional bool bRequiredCondition, optional name LogTag);
`warn(string OutputString, optional bool bRequiredCondition);

Object.uc에서 선언된 LogInternal과 WarnInternal 함수를 위한 래퍼 매크로들입니다. bRequiredCondition이 지정된 경우에는 조건이 true일 때만 메시지가 로그됩니다.

스크립트가 -final_release 스위치로 컴파일되는 경우에는 위의 두 매크로가 모두 무효화 됩니다.

logd

`logd(string OutputString, optional bool bRequiredCondition, optional name LogTag);

스크립트가 디버그 모드로 컴파일될 때만 유효화 된다는 점을 제외하면 `log 매크로와 똑같습니다.

이 매크로는 스크립트가 -final_release 스위치로 컴파일되는 경우에는 무효화 됩니다.

assert

`assert(bool bCondition);

내재적 표현인 Assert 를 위한 래퍼 매크로입니다.

이 매크로는 스크립트가 -final_release 스위치로 컴파일되는 경우에는 무효화 됩니다.

명령어를 이용한 스위치

스크립트 전처리기에 영향을 주기 위해 전달되는 다수의 스위치가 있습니다.

debug

UPP가 매크로 `debug를 정의하도록 합니다

final_release

UPP가 매크로 `final_release를 정의하고, 또 래퍼 매크로들을 (`log, `logd, `warn, `assert) 무효화 하도록 합니다.

nopreprocess

사전 처리되고 있는 매크로와 코멘트를 모두 중지하고 입력 파일의 텍스트를 그대로 클래스 팩토리에 전달합니다. 이것은 원래 타이밍과 속도 시험을 위한 것입니다. 그러나 매크로 외부에서 매크로 요청 문자를 포함하는 텍스트 파일을 요청하는 경우에는 이것을 사용해서 그 파일을 컴파일 할 수 있습니다 .

intermediate

UPP에게 컴파일하는 파일의 처리된 버전들을 저장할 것을 지시합니다. 이것은 전체 소스 트리의 시간 및 공간을 많이 잡아먹는 일이지만 매크로의 오류 추적에는 매우 중요한 일입니다. 이 파일들은
GameDirectory/PreprocessedFiles/<PackageName>/<ClassName>.uc에 저장됩니다.