PreProcessor Commands

Introduction

Preprocessor commands refer to the C(++) syntax used by the engine to 'pre process' the text inside a config.cpp, mission.sqm, or description.ext file. In fact, preprocessor commands apply to any BI game text file containing class statements, since these statements are 'scrunched' by the engine's internal C processor. The majority use however is in addons, and specifically, the config.cpp of the addon.

Preprocessor commands can also be used in script files, as long as the script is loaded using the preprocessfile command, or run via the execVM command.

There are a number of preprocessor commands recognized by the OFP and ArmA engine:

Comments

#include
#define
#undef
#ifdef
#ifndef
#else
#endif

__LINE__
__FILE__

(The macros __EXEC & __EVAL are discussed in the Config Parser article.)

Note for experienced users

The preprocessor mimics a subset of C preprocessor. While basic functionality is similar, the preprocessor is not fully C-conformant, as order of substitution of arguments in macro invocation is different than in C, which means some intricate nested macro constructs, especially when using token concatenation operator, may produce different results than in C.

Preprocessor commands

Comments

Though not technically a command, comments are handled by the preprocessor.

A comment is a line in your code that is not actually processed by the game engine. They are used to make your code more readable. The preprocessor removes all comments from the file, before it is processed. Therefore, any comments written in your code, will never actually be "seen" by the engine. They are for humans only.

There are two types of comments: single line comments and multi line comments.

//this is a single line comment
mycode = something; //only this part of the line is commented out
/* this
is a multi line
comment */

A single line comment begins after two forward slashes //, and ends at the next line break.

A multi line comment spans across line breaks. It starts with the characters /* and ends with the characters */

Both comment types can start anywhere in a line (they don't have to be at the beginning of a line).

#include

Syntax:

#include <PathAndFileName>
#include "PathAndFileName"

The purpose of an include statement is to share common definitions among several files (e.g. constants or functions).

The number of 'chunks' (ie, the number of included files) is solely at the author's discretion. In general, they will put similar elements together. For example, all icons will be in one file, all buildings in another, all cars in another, and so on. It is particularly common to put base characteristics of similar 'models' into a single 'base' file, and then include this file into multiple variations of that base model. For example, a base file may define a soldier with khaki trousers. A second soldier class could include this standard base, and then define specific variations (which may change the trousers to pink, and so on). The base characteristics of the model do not need to be repeated in the main body of the text for the second soldier, as it's duplicating work and contains no new information.

From the perspective of the game engine, the use of #include files is of no consequence, since the engine effectively processes all files as one file. All of the 'chunks' (the #included files) are merged into a single file for the purpose of compiling. Irrespective of how many #included files are used, the result is a single config.bin (config.bin is the resultant output of all this processing).

Processing continues at the beginning of the included file until it's end, at which point, processing continues at the statement after the initial #include. Thus, anything required by that included file (if anything at all), must have 'appeared' before the #include statement. It is quite common for included files to have #include statement(s) of their own, under which circumstance, processing continues at the beginning of that included file, and so on.

Example:

#include "someAddon\somePathInTheAddon\someFile.someExtension"

Note that the #include syntax string does not use a preceding backslash, unlike other file references (such as icons or models, etc.) used in BI game files. Also note, that there is no default file extension, and no trailing semi-colon.

Preprocessor commands do not have to be left-aligned, but can be indented, just like any other command.

NOTE - ArmA Tools Suite v1.14 Binarize.exe processing of #include is out of step with the capabilities of CfgConvert.exe.

If you desire single common include files in your addon config.cpp files in ArmA, CfgConvert.exe will support & process #includes that are

1. Relative both above & below the current folder of the config.cpp being processed.

ie. #include "..\inc\common.hpp"

#include "inc\common.hpp"

2. Absolute paths.

ie. #include "P:\Synide\common.hpp"

Basically, all the various ways you would want to use #include works perfectly with CfgConvert.exe. The same cannot be said of Binarize.exe however. If you wish to make use of the virtues of true relative #include statements in ArmA config's I suggest prior to running BinPBO the user manually converts the config to it's rapified/binarized format. There is one issue to this approach and that is you should not have the text version of the config named config.cpp as binarize.exe will attempt to process it and if it has #include statements like #include "..\common.hpp" will fail. So, call your text version (for example) config.cfg and make use of #include's full gambit of functionality and use CfgConvert.exe to pre-convert it to a config.bin which when BinPBO is run binarize.exe will quite happily make use of. All, this can be automated in a simple dos batch file.

#define

Syntax:

#define NAME VALUE

The referenced name is case sensitive when used. The value parameter can be optional (eg: when used with #ifdef alone), but is generally used. Within define arguments, the token 'concatenation operator' ##, and 'stringize operator' # may be used.

Define statements may be referred to by the term 'macro'. It is a macro in the same way macros are used in Microsoft Word - one macro can expand into a (very large) sequence of keystrokes. You can effectively understand #defines as

defineName = defineValue;

For example:

#define true  1
#define false 0

Macro Expansion

Macros can include tokens which are substituted when expanded as in the following example:

#define ICONS(icn) icon=\SomeAddon\icons\##icn;  \
                   model=\SomeAddon\##icn.p3d;   \
                   picture=\SomeAddon\##icn.paa

Then, using:

ICONS(Peter);
ICONS(Fred);

will be expanded during processing into:

icon=\SomeAddon\icons\Peter;
model=\SomeAddon\Peter.p3d;
picture=\SomeAddon\Peter.paa;
icon=\SomeAddon\icons\Fred;
model=\SomeAddon\Fred.p3d;
picture=\SomeAddon\Fred.paa;

The purpose of expanded macros as illustrated above is to allow simplified syntax, and to reduce typing load (and the likelihood of typos). In the case of the first example above, the #define macro creates more explicit, legible files, at the expense of increased typing.

Defines that span more than one line need the line-continuation symbol ("\") at the end of each line (see ICONS example above). Nothing is allowed to follow after this symbol - no comments, and not even spaces!

Nested defines:

Defines can be nested in each other, and they are all expanded. You can't seem to put a multi-line define inside of a multi-line define, nor can you pass a multi-line define in as a parameter of a macro.

When including defines in defines, the # operator works after expanding all defines. For example:

  1. define fn_myfunc compile preprocessfile 'myfile.sqf'
  2. define addquotes(x) #x 

addquotes(call fn_myfunc) result is: "call compile preprocessfile 'myfile.sqf'"

#undef

Syntax:

#undef NAME

This will undefine (delete) a macro previously set by the use of #define.

#ifdef

Syntax:

#ifdef NAME
  ...text that will be used if NAME is defined...
#endif

IFDEFs cannot be nested, as the preprocessor will generate an error if the outer definition doesn't exist.

#ifndef

Syntax:

#ifndef NAME
  ...text that will be used if NAME isn't defined...
#endif

#else

Syntax:

#ifndef NAME
  ...text that will be used if NAME isn't defined...
#else
  ...text that will be used if NAME is defined...
#endif

#endif

This ends a conditional block as shown in the descriptions of #ifdef and #ifndef above.

__LINE__

This keyword gets replaced with the line number in the file where it is found. For example, if __LINE__ is found on the 10th line of a file, the word __LINE__ will be replaced with the number 10.

__FILE__

This keyword gets replaced with the fully qualified filename of this file.

For a config.cpp converted to a bin:

 _file=__FILE__;

result:

 _file= "P:\CWR2\Cars\cwr2_brdm\config.cpp";

For scripts packed into an addon, a relative path is displayed (relative to the program's exe file). For scripts in a mission folder, a direct path is displayed (drive letter and full path). [Note: untested what happens when this is used inside of a config]

Example:

//recurse.sqf
_i = _this select 0;
if (_i < 100) then {[_i + 1] execVM __FILE__};