Language Overview

A very simple CDL script would look like this:

cdl_package CYGPKG_ERROR {
    display       "Common error code support"
    compile       strerror.cxx
    include_dir   cyg/error
    description   "
        This package contains the common list of error and
        status codes. It is held centrally to allow
        packages to interchange error codes and status
        codes in a common way, rather than each package
        having its own conventions for error/status
        reporting. The error codes are modelled on the
        POSIX style naming e.g. EINVAL etc. This package
        also provides the standard strerror() function to
        convert error codes to textual representation."
}

This describes a single package, the error code package, which does not have any sub-components or configuration options. The package has an internal name, CYGPKG_ERROR, which can be referenced in other CDL scripts using e.g. requires CYGPKG_ERROR. There will also be a #define for this symbol in a configuration header file. In addition to the package name, this script provides a number of properties for the package as a whole. The display property provides a short description. The description property involves a rather longer one, for when users need a bit more information. The compile and include_dir properties list the consequences of this package at build-time. The package appears to lack any on-line documentation.

Packages could be even simpler than this. If the package only provides an interface and there are no files to be compiled then there is no need for a compile property. Alternatively if there are no exported header files, or if the exported header files should go to the top-level of the install/include directory, then there is no need for an include_dir property. Strictly speaking the description and display properties are optional as well, although application developers would not appreciate the resulting lack of information about what the package is supposed to do.

However many packages tend to be a bit more complicated than the error package, containing various sub-components and configuration options. These are also defined in the CDL scripts and in much the same way as the package. For example, the following excerpt comes from the infrastructure package:

cdl_component CYGDBG_INFRA_DEBUG_TRACE_ASSERT_BUFFER {
    display       "Buffered tracing"
    default_value 1
    active_if     CYGDBG_USE_TRACING
    description   "
        An output module which buffers output from tracing and
        assertion events. The stored messages are output when an
        assert fires, or CYG_TRACE_PRINT() (defined in
        <cyg/infra/cyg_trac.h>) is called. Of course, there will
        only be stored messages if tracing per se (CYGDBG_USE_TRACING)
        is enabled above."

    cdl_option CYGDBG_INFRA_DEBUG_TRACE_BUFFER_SIZE {
        display       "Trace buffer size"
        flavor        data
        default_value 32
        legal_values  5 to 65535
        description   "
            The size of the trace buffer. This counts the number of
            trace records stored. When the buffer fills it either
            wraps, stops recording, or generates output."
    }

    …
}

Like a cdl_package, a cdl_component has a name and a body. The body contains various properties for that component, and may also contain sub-components or options. Similarly a cdl_option has a name and a body of properties. This example lists a number of new properties: default_value, active_if, flavor and legal_values. The meaning of most of these should be fairly obvious. The next sections describe the various CDL commands and properties.

There is one additional and very important point: CDL is not a completely new language; instead it is implemented as an extension of the existing Tcl scripting language. The syntax of a CDL script is Tcl syntax, which is described below. In addition some of the more advanced facilities of CDL involve embedded fragments of Tcl code, for example there is a define_proc property which specifies some code that needs to be executed when the component framework generates the configuration header files.