The cdlOptions definition
Work in progress.
Purpose
Define a map of option objects (basic units of configurability).
Syntax
{
"cdlOptions": {
"<name>": {
"display": "<short name>",
"description": "<long text>",
... option members ...
}
}
}
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. Options may have associated constraints, so if an option is enabled, certain conditions must be satisfied elsewhere in the configuration. Options usually have direct consequences, such as preprocessor #define symbols in a configuration header file.
Each cdlOptions object is defined as a JSON object that has an 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/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 are 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).
If active and enabled, a cdlOptions object can generate preprocessor #define lines in a configuration header file (if the generatedDefinition property is also defined) and decide if a set of source files are included in the build process (if the sourceFile property is also defined).
Containers
The cdlOptions objects are not containers, so they cannot hold other objects like cdlOptions or cdlComponents).
Properties
-
activeIf- an array of boolean expressions to be evaluated; if all are true, the active state of this option remains true -
compilerIncludeFolders- an array of folder paths that should be used during the built if this option is active and enabled -
compilerOptions- a map of toolchain specific objects with compiler options to be used during the build if this option is active and enabled -
compilerPreprocessorSymbols- a map of toolchain specific objects with preprocessor symbols to be used during the build if this option is active and enabled -
compilerSourceFiles- an array of source file paths that should be built if this option is active and enabled -
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 -
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 -
generatedDefinition- a valid C/C++ preprocessor identifier to be defined in the header file if the option is active and enabled -
generatedFile- 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 -
parent- provides a method to break the default hierarchy and directly specify the xCDL path of the parent of this option -
requires- an array of boolean goal expressions usually referring to other objects that need to be enabled for this option to be 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": {
"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).",
"generatedDefinition": "OS_DEBUG_INFRA_DEBUG_PRECONDITIONS",
"defaultEnable": true
}
}
}