Skip to main content

The cdlComponents definition

note

Work in progress.

Purpose​

Define a map of component objects (generic units of functionality).

Syntax​

{
    "cdlComponents": {
        "<name>": {
            "display": "<short name>",
            "description": "<long text>",

            ... component members ...
        }
    }
}

Description​

cdlComponents objects are configuration objects that can contain additional options and subcomponents. A cdlComponents object can have the same properties as an cdlOptions object. Additionally, the includeCDLs property enables the configuration definitions to be distributed across multiple files, to be included below the current object in the configuration hierarchy.

Each cdlComponents 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.

Similarly to cdlOptions objects, if active and enabled, cdlComponents objects can generate preprocessor #define lines in a configuration header file and decide if a set of source files are included in the build process.

Containers​

The cdlComponents objects are inherently containers, allowing them to include cdlComponents, cdlOptions, cdlInterfaces that should be organized below this object in the configuration hierarchy. These objects can be defined either as embedded children or can be read from included files.

Properties​

  • activeIf - an array of boolean expressions to be evaluated; if all are true, the active state of this component remains true
  • childrenGeneratedFile - the file path of the header, relative to the build folder, where the child nodes will generate a definition (if missing, this is inherited from the parent node)
  • compilerIncludeFolders - an array of folder paths that should be used during the built if this component is active and enabled
  • compilerOptions - a map of toolchain specific objects with compiler options to be used during the build if this component is active and enabled
  • compilerPreprocessorSymbols - a map of toolchain specific objects with preprocessor symbols to be used during the build if this component is active and enabled
  • compilerSourceFiles - an array of source file paths that should be built if this component 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 component can be enabled/disabled by the user during the configuration process
  • defaultEnabled - a boolean expression that provides an initial value for the component's enabled/disabled state
  • defaultValue - an expression to be used as a default value for this component when the user does not define it explicitly during the configuration process
  • description - provides a reasonably long paragraph with a textual description for the component
  • display - provides a node name for the component when rendered in the configuration hierarchy
  • docsUrl - provides the location of online documentation for the component
  • generatedDefinition - a valid C/C++ preprocessor identifier to be defined in the header file if the component is active and enabled
  • generatedFile - the full file path of the header where the component will generate a definition (if missing, inherited from the parent node)
  • implements - an array of xCDL paths of the interfaces implemented by this component
  • includeCDLs - an array of paths to xCDL metadata files to be parsed, with their objects to included as children of the current node
  • legalValues - an array of restrictions that the value of this component must satisfy
  • parent - provides a method to break the default hierarchy and directly specify the xCDL path of the parent of this component
  • requires - an array of boolean goal expressions usually referring to other objects that need to be enabled for this component to be enabled
  • valueFormat - control how the component's value will appear in the configuration header file
  • valueType - specify the type of the variable associated with this component (none | bool | int | float | string)

Example​

A boolean component, enabled by default.

{
    "cdlComponent": {
        "useAsserts": {
            "display": "Use asserts",
            "description": "If this component is enabled, assertions in the code are tested at run-time. Assert functions (OS_ASSERT()) are defined in `include/os/infra/os_ass.h` within the install tree. If the component is disabled, these result in no additional object code and no checking of the asserted conditions.",
            "defaultEnable": true,
            "includeCDLs": [ "assert.json" ]
        }
    }
}

See also​

eCos reference​