option Configuration File Directive

The option directive defines options for one of the tasks involved in a build. For example, option directives select options that apply during the compile, link, and other steps of a build.

This diagram shows the syntax of the option directive:

The option directive has the following parameters:

option_group
If this parameter is included, the option directive defines a group and this parameter is the name of the group. The group name can be used in subsequent option directives to represent options listed to the right of the assignment operator. After a group has been defined, you cannot redefine it.

For example, the first line in the following example defines the group nobool. The second line uses nobool in an option directive that applies the group of options to a source directive. The third line fails because it tries to change nobool.

option nobool = lang(noKeyword, true), lang(noKeyword, false),
                lang(noKeyword, bool)
option nobool { source "myprog.cpp" }
option nobool = null   // error: redefining nobool is not allowed

option_list
This parameter is a list of one or more option names and option values, separated by commas. In the second line of the preceding example, nobool represents a list of three options. The option names are keywords reserved by the process to which the option applies. For example, lang(noKeyword, ...) is a language option that applies to C++ source files. Option values can be variables or data elements such as numbers, strings, or string lists. File names in strings can include relative or absolute paths.

An item in an option list also may be the name of an option group, if that group is defined in a previous option directive. For example, the following lines define a group called x for options lang(staticInlineLinkage, no) and lang(offsetOfNonPODClasses). This group of options, as well as macros(global), is then applied to source files myprog.cpp and myfuncs.cpp.

option x = lang(staticInlineLinkage, no), 
           lang(offsetOfNonPODClasses)
option macros(global), x {
   source "myprog.cpp", '..\myfuncs.cpp'
}

A value can be an unquoted string, if it looks like an identifier. For example, the word no in the lines above is not enclosed within quotation marks. The strings "myprog.cpp" and '..\myfuncs.cpp' must be in quotation marks because they contains characters that are not allowed in identifiers. To prevent the backslash from being interpreted as the arming character of an escape sequence, '..\myfuncs' is in single quotation marks rather than double quotation marks.

The following table shows why you should use unquoted strings with care:

Directive Type of bar Equivalent Directive
// no prior reference to bar
option mygroup = define(bar)
unquoted string option mygroup = define("bar")
bar = "foo"
option mygroup = define(bar)
variable with value "foo" option mygroup = define("foo")

directive_block
This parameter is an optional block of directives. If a block is included, it must be enclosed in braces, { and }, even if it contains only one directive. The options in the option list apply to all relevant directives in the directive block.

Source and target directives in the directive block determine which of the options are processed, and in what order. Options can accumulate or override other options depending on the purpose of the option and the process that handles them.

null
When used in the context of a list of options, this keyword represents an empty list.

Examples of the option Directive


Configuration Files
How Configuration Files Are Processed


Change a Build Setup
Build


Configuration File Directives
Build Options