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
![]()
Configuration File Directives
Build Options
