Skip to main content

The cdlPackage definition

note

Work in progress.

Purpose​

Define a package (a specialized component that can be distributed independently).

Syntax​

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

        ... package members ...
    }
}

Description​

The cdlPackage object is the unit of software distribution. It is also a configuration option in that users can choose whether or not a particular package is loaded into the configuration. It is also a configuration component in that it can contain additional components and options in a hierarchy.

A cdlPackage can have most of the properties and behaviour of a cdlComponents object, but with some limitations (see the Unavailable properties below).

The project top-level xCDL file must begin with a cdlPackage object.

Containers​

The cdlPackage is inherently a container, so it may include cdlComponents, cdlOptions, cdlInterfaces objects that will go below this object in the configuration hierarchy.

Properties​

  • activeIf - an array of boolean expressions to be evaluated; if all are true, the active state of this package 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 package is active and enabled
  • compilerOptions - a map of toolchain specific objects with compiler options to be used during the build if this package is active and enabled
  • compilerPreprocessorSymbols - a map of toolchain specific objects with preprocessor symbols to be used during the build if this package is active and enabled
  • compilerSourceFiles - an array of source file paths that should be built if this package is active and enabled
  • defaultEnabled - a boolean expression that provides an initial value for the package's enabled/disabled state
  • defaultValue - an expression to be used as a default value for this package 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 package is active and enabled
  • generatedFile - the full file path of the header where the package will generate a definition (if missing, inherited from the parent node)
  • implements - an array of xCDL paths of the interfaces implemented by this package
  • includeCDLs - an array of paths to xCDL metadata files to be parsed, with their objects to included as children of the current node
  • name - the internal name used to identify the package
  • parent - provides a method to break the default hierarchy and directly specify the xCDL path of the parent of this package
  • requires - an array of boolean goal expressions usually referring to other objects that need to be enabled for this package to be enabled

Unavailable properties​

  • computed - always false; the package's value cannot be computed
  • configurable - always true; packages can always be enabled/disabled by the user during the configuration process
  • valueType - always bool; packages do not have an associated value, they return 1 if enabled
  • valueFormat - if the header definition is generated, the value will always be (1) [TODO: perhaps booleans can be formatted as true/false]
  • legalValues - no restrictions can apply to package values

Example​

{
    "cdlPackage": {
        "name": "infra",
        "display" : "Infrastructure",
        "description": "Common types and useful macros. Tracing and assertion facilities. Package startup options.",
        "generatedFile": "os/infra/infra.h",
        "compilerSourceFiles": [
            "startup.cpp",
            "prestart.cpp",
            "pkgstart.cpp",
            "userstart.cpp"
        ]
    }
}

See also​

eCos reference​