Preprocessor - Revision history

113.22.250.67: At the end of the first paragraph, changed "to to" to "to" only.

2011-04-06T23:47:18Z

At the end of the first paragraph, changed "to to" to "to" only.

Eliot: Typos etc

2010-08-25T21:25:12Z

Typos etc

Eliot: /* The Preprocessor */

2010-04-21T23:46:26Z

‎The Preprocessor

Eliot: Added the us navbox

2010-04-21T17:03:14Z

Added the us navbox

HoMeRSiMpSoN: New page: ==The Preprocessor== The UT3 UnrealScript compiler now supports a preprocessor. The preprocessor works much like the C++ preprocessor and is perfect for supporting conditional compilation ...

2008-08-15T15:19:16Z

New page: ==The Preprocessor== The UT3 UnrealScript compiler now supports a preprocessor. The preprocessor works much like the C++ preprocessor and is perfect for supporting conditional compilation ...

New page

==The Preprocessor==
The UT3 UnrealScript compiler now supports a preprocessor. The preprocessor works much like the C++ preprocessor and is perfect for supporting conditional compilation via macros.
Macros are file-scope, meaning a macro defined on line X of the script class (.uc) file is only usable on lines X+n in that file and not in any other files (unless it is included in another .uc file). However, you can create a .uci file to to include macros in your .uc file.
==Command-line Switches==
===-debug===
Using a -debug command line option causes a ''`debug'' macro to be defined.
===-final_release===
Using a -final-release command line option causes UPP to define the macro ''`final_release'', as well as disable all wrapper macros (''`log'', ''`logd'', ''`warn'', ''`assert''). (see below).
===-nopreprocess===
Using a -nopreprocess command line option turns off all macro and comment preprocessing.
===-intermediate===
Using a -intermediate command line option will save the processed versions of the files compiled (for tracking down errors in macros) to <My Documents>\PreprocessedFiles\<package>\<class>.uc

==Using Macros==

===`define===
''`define <macroname>[<(paramA[,paramB...])>] [<macrodefinition>]'' 
Defines the named macro to expand to the given definition. Parameters for the macro are specified in a typeless function parameter list immediately after the name of the macro. In the macro definition, the parameters are referenced by name and prefixed with a backtick. Although I have not yet verified, my research indicated that you can also use the the special macro ''`#'' to repesent the number of parameters specified, although I have not verified this though. If you don't give the macro a definition, the macro is still defined but expands to an empty string. You can also define a macro to represent a constant value.

Equivalently, the name of the macro can be enclosed in { } after the tick as in ''`{hello}''. This makes it possible to "insert" the expansion of a macro into the middle of text that does not have conveniently placed whitespace.
<uscript>hippo`{hello}potamus
</uscript>
Other examples:
<uscript>`define SOME_CONST 1

`define hello "Hello, World!"

`define SomeMacro(param1, param2) CallMyFunction(`param1, `param2)</uscript>

===`if / `else / `endif===
''`if(<string>)''

''`else''

''`endif'' 
Basically, this is conditional compilation. The text between ''`if'' and either ''`else'' (if present) or ''`endif'' are emitted into the processed output if the condition is true (if it is expanded to a non-empty string); if the condition is not true, only the end-of-line characters are emitted so that the line numbers in the processed text match up with those in the original text. The text between the (optional) ''`else'' and ''`endif'' are emitted if the original condition is false.

This may be obvious, but any macros used in the non-emitted code (in the ''`else'' if the statment is true, or before the ''`else'' if the statement is true) are not evaluated (except for nested ''`if'' blocks).
<uscript>`if(`isdefined(SOME_CONST))
// do some code here if SOME_CONST can be expanded to a non-empty string...
`endif

`if(`isdefined(SOME_OTHER_CONST))
// do some code here if SOME_CONST can be expanded to a non-empty string...
`else
//do some code here if SOME_CONST can NOT be expanded to a non-empty string...
`endif</uscript>
===`include===
''`include(<filename>)'' 
Includes the text within the file <filename> at the macro's location in the code. By default, <filename> is relative to the directory specified by the EditPackagesInPath of the [Editor.EditorEngine] section of UTGame.ini file. If you specify only the filename (no directory), it will search for the include file in the classes directory for the package being compiled.
<uscript>`include( MyStuff.uci )

`include( MyPackage/Classes/MyGlobals.uci )
</uscript>
===`isdefined / `notdefined===
''`isdefined(<macroname>)'' 
''`notdefined(<macroname>)'' 
Evaluates to the string "1" if the macro is (''`isdefined'') or is not (''`notdefined'') defined, regardless of the macros definition. This useful for conditional compilation. You can include code only in debug or release builds, or based on other defined constants.
<uscript>`if(`isdefined(SOME_CONST))
// do some code here if SOME_CONST is defined...
`endif

`if(`notdefined(SOME_CONST))
// do some code here if SOME_CONST is NOT defined...
`endif
</uscript>
===`undefine===
''undefine(<macroname>)'' 
Remove the current definition of <macroname>.
<uscript>`undefine(SOME_CONST)</uscript>
==Predefined Macros for Logging==
There is a good reason to use the ''`log'' and ''`warn'' macros instead of '''LogInternal()''' and '''WarnInternal()''' functions. If you use the -final_release command line option when you "make", it will turn off all logging because ''`log'' and ''`warn'' are empty defines when using -final_release. However, the '''LogInternal()''' and '''WarnInternal()''' function(s) will still be called if you use them directly. Using the macro to write to the log for debug info will not incur a function call overhead in a release build.

More importantly, it also appears that calls to LogInternal (or anything *Internal) generate compile errors when using -final_release.
===`log / `warn===
''`log(string OutputString, optional bool bRequiredCondition, optional name LogTag)'' 
''`warn(string OutputString, optional bool bRequiredCondition)'' 
Wrapper macros for the LogInternal and WarnInternal functions declared in Object.uc. If bRequiredCondition is specified, the message will only be logged if the condition is true.

Both macros are disabled if scripts are compiled with the -final_release command line option.
===`logd===
''`logd(string OutputString, optional bool bRequiredCondition, optional name LogTag)'' 
Identical to the `log macro, except that it is only enabled if scripts are compiled in debug mode.

This macro is disabled if scripts are compiled with the -final_release switch.
===`assert===
''`assert(bool bCondition)'' 
Wrapper macro for the Assert intrinsic expression.

This macro is disabled if scripts are compiled with the -final_release switch.

@@ Line 2: / Line 2: @@
 The preprocessor works much like the C++ preprocessor and is perfect for supporting conditional compilation via macros.
-Macros are file-scope, meaning a macro defined on line X of the script class ([[.uc]]) file is only usable on lines X+n in that file and not in any other files (unless it is included in another .uc file). However, you can create a [[.uci]] file to to include macros in your .uc file.
+Macros are file-scope, meaning a macro defined on line X of the script class ([[.uc]]) file is only usable on lines X+n in that file and not in any other files (unless it is included in another .uc file). However, you can create a [[.uci]] file to include macros in your .uc file.
 ==Command-line Switches==

@@ Line 1: / Line 1: @@
-Starting with [[Unreal Engine 3]] The UnrealScript compiler now supports a preprocessor.
+Starting with [[Unreal Engine 3]] The UnrealScript compiler now supports a [[wp:preprocessor|preprocessor]].
 The preprocessor works much like the C++ preprocessor and is perfect for supporting conditional compilation via macros.
-Macros are file-scope, meaning a macro defined on line X of the script class (.uc) file is only usable on lines X+n in that file and not in any other files (unless it is included in another .uc file). However, you can create a .uci file to to include macros in your .uc file.
+Macros are file-scope, meaning a macro defined on line X of the script class ([[.uc]]) file is only usable on lines X+n in that file and not in any other files (unless it is included in another .uc file). However, you can create a [[.uci]] file to to include macros in your .uc file.
 ==Command-line Switches==
@@ Line 17: / Line 18: @@
 ===`define===
 ''`define <macroname>[<(paramA[,paramB...])>] [<macrodefinition>]''<br>
-Defines the named macro to expand to the given definition. Parameters for the macro are specified in a typeless function parameter list immediately after the name of the macro. In the macro definition, the parameters are referenced by name and prefixed with a backtick. Although I have not yet verified, my research indicated that you can also use the the special macro ''`#'' to repesent the number of parameters specified, although I have not verified this though. If you don't give the macro a definition, the macro is still defined but expands to an empty string. You can also define a macro to represent a constant value.
+Defines the named macro to expand to the given definition. Parameters for the macro are specified in a typeless function parameter list immediately after the name of the macro. In the macro definition, the parameters are referenced by name and prefixed with a backtick. Although I have not yet verified, my research indicated that you can also use the the special macro ''`#'' to represent the number of parameters specified, although I have not verified this though. If you don't give the macro a definition, the macro is still defined but expands to an empty string. You can also define a macro to represent a constant value.
 Equivalently, the name of the macro can be enclosed in { } after the tick as in ''`{hello}''. This makes it possible to "insert" the expansion of a macro into the middle of text that does not have conveniently placed whitespace.
@@ Line 37: / Line 38: @@
 Basically, this is conditional compilation. The text between ''`if'' and either ''`else'' (if present) or ''`endif'' are emitted into the processed output if the condition is true (if it is expanded to a non-empty string); if the condition is not true, only the end-of-line characters are emitted so that the line numbers in the processed text match up with those in the original text.  The text between the (optional) ''`else'' and ''`endif'' are emitted if the original condition is false.
-This may be obvious, but any macros used in the non-emitted code (in the ''`else'' if the statment is true, or before the ''`else'' if the statement is true) are not evaluated (except for nested ''`if'' blocks).
+This may be obvious, but any macros used in the non-emitted code (in the ''`else'' if the statement is true, or before the ''`else'' if the statement is true) are not evaluated (except for nested ''`if'' blocks).
 <uscript>`if(`isdefined(SOME_CONST))
       // do some code here if SOME_CONST can be expanded to a non-empty string...
@@ Line 49: / Line 50: @@
 ===`include===
 ''`include(<filename>)''<br>
-Includes the text within the file <filename> at the macro's location in the code. By default, <filename> is relative to the directory specified by the EditPackagesInPath of the [Editor.EditorEngine] section of UTGame.ini file. If you specify only the filename (no directory), it will search for the include file in the classes directory for the package being compiled.
+Includes the text within the file <filename> at the macro's location in the code. By default, <filename> is relative to the directory specified by the '''EditPackagesInPath''' of the <code>[Editor.EditorEngine]</code> section of <code>UTGame.ini</code> file. If you specify only the filename (no directory), it will search for the include file in the classes directory for the package being compiled.
 <uscript>`include( MyStuff.uci )
@@ Line 73: / Line 74: @@
 There is a good reason to use the ''`log'' and ''`warn'' macros instead of '''LogInternal()''' and '''WarnInternal()''' functions. If you use the -final_release command line option when you "make", it will turn off all logging because ''`log'' and ''`warn'' are empty defines when using -final_release. However, the '''LogInternal()''' and '''WarnInternal()''' function(s) will still be called if you use them directly.  Using the macro to write to the log for debug info will not incur a function call overhead in a release build.
-More importantly, it also appears that calls to LogInternal (or anything *Internal) generate compile errors when using -final_release.
+More importantly, it also appears that calls to '''LogInternal''' (or anything *Internal) generate [[compiler errors]] when using -final_release.
 ===`log / `warn===
-''`log(string OutputString, optional bool bRequiredCondition, optional name LogTag)''<br>
+{{code|`log([[string]] OutputString, [[optional]] [[bool]] bRequiredCondition, [[optional]] [[name]] LogTag)}}
-''`warn(string OutputString, optional bool bRequiredCondition)''<br>
+{{code|`warn([[string]] OutputString, [[optional]] [[bool]] bRequiredCondition)}}
-Wrapper macros for the LogInternal and WarnInternal functions declared in Object.uc. If bRequiredCondition is specified, the message will only be logged if the condition is true.
+Wrapper macros for the '''LogInternal''' and '''WarnInternal''' functions declared in Object.uc. If '''bRequiredCondition''' is specified, the message will only be logged if the condition is true.
 Both macros are disabled if scripts are compiled with the -final_release command line option.
 ===`logd===
-''`logd(string OutputString, optional bool bRequiredCondition, optional name LogTag)''<br>
+{{code|`logd([[string]] OutputString, [[optional]] [[bool]] bRequiredCondition, [[optional]] [[name]] LogTag)}}
 Identical to the `log macro, except that it is only enabled if scripts are compiled in debug mode.
 This macro is disabled if scripts are compiled with the -final_release switch.
 ===`assert===
-''`assert(bool bCondition)''<br>
+{{code|`assert([[bool]] bCondition)}}
 Wrapper macro for the Assert intrinsic expression.

← Older revision		Revision as of 17:03, 21 April 2010
Line 89:		Line 89:

	This macro is disabled if scripts are compiled with the -final_release switch.		This macro is disabled if scripts are compiled with the -final_release switch.
		+
		+	{{navbox unrealscript}}