The eCos Component Writer's Guide
Prev |  | Next

# Chapter 3. The CDL Language

The CDL language is a key part of the eCos component framework. All packages must come with at least one CDL script, to describe that package to the framework. The information in that script includes details of all the configuration options and how to build the package. Implementing a new component or turning some existing code into an eCos component always involves writing corresponding CDL. This chapter provides a description of the CDL language. Detailed information on specific parts of the language can be found in Chapter 5.

# 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.

Prev | Home | Next
Making a Package Distribution |  | CDL Commands