Skip to main content

The parent definition

note

Work in progress.

Purpose​

Control the placement of an option within the configuration hierarchy.

Syntax​

{
    "cdlOptions": {
        "<name>": {
            ...
            "parent": "<string>",
            ...
        }
    }
}

The value of the parent property is a string containing the xCDL path of the parent object.

Default value​

If missing (the usual case), the surrounding object is considered the natural parent of this object. If none, the package object in the parent folder is used.

Description​

Configuration objects exist within a hierarchy of packages and components. By default, an object's position in the hierarchy is determined by its location within the xCDL scripts, based on its position in the folder hierarchy. Packages are generally placed at the top level of the configuration. Any cdlComponents or cdlOptions objects defined at the same level as the cdlPackage object in a package's top-level xCDL script are placed immediately below that package in the hierarchy. Any cdlOptions or cdlComponents objects defined within a cdlPackage or cdlComponents object, or read in as a result of processing an object's includeCDLs property, will be placed immediately below that cdlPackage or cdlComponents in the hierarchy.

In some cases, it is useful to specify an alternative position in the hierarchy for a given object. For example, it is often convenient to re-parent device driver packages below the io package in the configuration hierarchy, reducing the number of packages at the top level and making navigation easier. The parent property can be used to achieve this.

The value of the parent property is a string, with the xCDL path of a cdlPackage or cdlComponents object.

Re-parenting to another package​

Although the parent property affects an object's position in the overall hierarchy and whether or not that object is active, a re-parented object still belongs to the package that defines it. By default, any #define statements will be generated into that package's configuration header file. Any compilerSourceFiles properties can only reference source files present in that actual package, and it is not possible to cause a file in another package to be built by re-parenting.

Implementation detail

To implement this, objects should keep track of two parents, the one where the definition resides and the re-parented one (package-parent and activation-parent).

As a special case, if an empty string is specified for the parent, the object is placed at the top of the hierarchy, ahead of any packages not explicitly re-parented in this way. This feature is useful for configuration options such as global preferences and default compiler flags.

Example​

{
  "cdlComponents": {
    "trace": {
      ...
      "cdlComponents": {
        "buffer": {
          "display": "Buffered tracing",
          "generatedDefinition": "OS_DEBUG_INFRA_DEBUG_TRACE_ASSERT_BUFFER",
          "defaultEnable": true,
          "activeIf": [ "isEnabled('trace')" ]
        }
      },
      "cdlOptions": {
        "size": {
          "display": "Trace buffer array size",
          "parent": "buffer",
          "valueType": "int",
          "defaultValue": "32",
          "legalValues": "5 to 65535"
        }
      }
    }
  }
}

See also​

eCos reference​