cdlOptions object
Work in progress.
Purpose
Define an array of option objects (basic units of configurability).
Syntax
{
"cdlOptions": [
{
"name": "<option name>",
"display": "<short name>",
"description": "<long text>",
... option members ...
}
],
...
}
The value of the cdlOptions property is an array of option objects,
each having a name and a body. Names are map keys and must be unique within
a parent.
Description
cdlOptions objects are the basic units of configurability. Generally, each
cdlOptions object corresponds to a single user choice. Typically, there is a
certain amount of information associated with an option to assist the user in
manipulating it, such as a displayed name and a textual description.
There are also limits on the possible values that the user can choose, so an
option may be a simple yes-or-no choice or something more complex, like a stack
size or a device name.
Each cdlOptions object is defined as a JSON object that has a name and a
body. Names are map keys and must be unique within a parent.
The user choice is expressed during the configuration process and is reflected
in the enabled or disabled status of the option. For options with associated
values, it is also possible for the user to define a value. If a value is
missing, a default value, either implicit or defined as the defaultValue
property, is applied. For these options, it is also possible to define limits on
the possible values that the user can choose.
A separate class of options is the computed options, whose values cannot be
set by the user but are computed according to a given expression.
Options may have associated constraints, so if an option is enabled, certain
conditions must be satisfied elsewhere in the configuration for it to be active
(the activeIf property), or it may mandate that some objects be enabled or
disabled (the requires property).
Options usually have direct consequences.
If active and enabled, a cdlOptions object can generate preprocessor #define
lines in a configuration header file and decide if a set of source files
are included in the build
process (if the sourceFiles property is also defined).
Containers
The cdlOptions objects are not containers, so they cannot hold other objects
like cdlOptions or cdlComponents. They are leaves in the configuration
hierarchy, and they can only have properties that define their behaviour
and consequences.
Properties
-
activeIf- an array of boolean expressions to be evaluated; if all are true, the active state of this option remains true -
computed- the option's value is not directly user-modifiable; it is computed using a suitable expression -
configurable- a boolean expression that provides additional information to a configuration tool, controlling whether this option can be enabled/disabled by the user during the configuration process -
customDefine- a valid C/C++ preprocessor identifier to be defined in the header file if the option is active and enabled -
defaultEnabled- a boolean expression that provides an initial value for the option's enabled/disabled state -
defaultValue- an expression to be used as a default value for this option when the user does not define it explicitly during the configuration process -
headerFile- the full file path of the header where the option will generate a definition (if missing, inherited from the parent node) -
implements- an array of xCDL paths of the interfaces implemented by this option -
legalValues- an array of restrictions that the value of this option must satisfy -
privateCompilerOptions- a map of toolchain-specific objects with compiler private options used during the build if this option is active and enabled -
privateDefines- a map of toolchain-specific objects with preprocessor macros used during the build if this option is active and enabled -
privateIncludeFolders- an array of folder paths used during the build if this option is active and enabled -
publicCompilerOptions- a map of toolchain-specific objects with compiler public options used during the build and propagated upwards if this option is active and enabled -
publicDefines- a map of toolchain-specific objects with preprocessor macros used during the build and propagated upwards if this option is active and enabled -
publicIncludeFolders- an array of folder paths used during the build and propagated upwards if this option is active and enabled -
requires- an array of boolean goal expressions usually referring to other objects that need to be enabled for this option to be enabled -
sourceFiles- an array of source file paths that should be built if this option is active and enabled -
valueType- specify the type of the variable associated with this option (none | bool | int | float | string) -
valueFormat- control how the option's value will appear in the configuration header file
Example
A boolean option, enabled by default.
{
"cdlOptions": [
{
"name": "preconditions",
"display": "Preconditions",
"description": "This option allows individual control of preconditions. A precondition is one type of assert, which it is useful to control separately from more general asserts. The function is OS_PRECONDITION(condition,msg).",
"customDefine": "OS_DEBUG_INFRA_DEBUG_PRECONDITIONS",
}
]
}