The eCos Component Writer's Guide
Prev |  | Next

# `cdl_package`

## Name

Command `cdl_package` -- Define a package, a component that can be distributed

## Synopsis

    cdl_package <name> {
        …
    }

## Description

A package is a unit of distribution. It is also a configuration option in that users can choose whether or not a particular package is loaded into the configuration, and which version of that package should be loaded. It is also a component in that it can contain additional components and options in a hierarchy.

The top-level CDL script for a package should begin with a `cdl_package` command. This can contain most of the properties that can be used in a `cdl_option` command, and a number of additional ones which apply to a package as a whole. It is also possible to include `cdl_component`, `cdl_interface` and `cdl_option` commands in the body of a package. However all configuration entities that occur at the top level of the script containing the `cdl_package` command are automatically placed below that package in the configuration hierarchy, so putting them inside the body has no effect.

The following properties cannot be used in the body of a `cdl_package` command:

flavor

  Packages always have the flavor `booldata`.

default_value

  The value of a package is its version number. This is specified at the time the package is loaded into the configuration, and cannot be calculated afterwards. Typically the most recent version of the package will be loaded.

legal_values

  The legal values list for a given package is determined by which versions of that package are installed in the component repository, and cannot be further constrained in the CDL scripts.

calculated

  The value of a package is always selected at the time that it is loaded into the configuration, and cannot be re-calculated afterwards.

script

  This would be redundant since the CDL script containing the `cdl_package` command acts as that package's script.

`cdl_package` is implemented as a Tcl command that takes two arguments, a name and a body. The name must be a valid C preprocessor identifier: a sequence of upper or lower case letters, digits or underscores, starting with a non-digit character; identifiers beginning with an underscore should normally be avoided because they may clash with system packages or with identifiers reserved for use by the compiler. Packages should always have unique names within a given component repository. For a recommended naming convention see the Section called Package Contents and Layout in Chapter 2.

The second argument to `cdl_package` is a body of properties and other commands, typically surrounded by braces so that the Tcl interpreter treats it as a single argument. This body will be processed by a recursive invocation of the Tcl interpreter, extended with additional commands for the various properties that are allowed inside a `cdl_package`. The valid commands are:

active_if

  Allow additional control over the active state of this package.

`cdl_component`

  Define a component which should appear immediately below this package in the configuration hierarchy.

`cdl_interface`

  Define an interface which should appear immediately below this package in the configuration hierarchy.

`cdl_option`

  Define an option which should appear immediately below this package in the configuration hierarchy.

compile

  List the source files that should be built for this package.

define

  Specify additional `#define` symbols that should go into the package's configuration header file.

define_format

  Control how the package's value will appear in the global configuration header file `pkgconf/system.h`

define_header

  Specify the configuration header file that will be generated for this package.

define_proc

  Use a fragment of Tcl code to output additional data to configuration header files.

description

  Provide a textual description for this component.

display

  Provide a short string describing this component.

doc

  The location of on-line documentation for this component.

hardware

  This package is tied to specific hardware.

if_define

  Output a common preprocessor construct to a configuration header file.

implements

  Enabling this component provides one instance of a more general interface.

include_dir

  Specify the desired location of this package's exported header files in the install tree.

include_files

  List the header files that are exported by this package.

library

  Specify which library should contain the object files generated by building this package.

make

  An additional custom build step associated with this component, resulting in a target that should not go directly into a library.

make_object

  An additional custom build step associated with this component, resulting in an object file that should go into a library.

no_define

  Suppress the normal generation of the package's `#define` in the global configuration header file `pkgconf/system.h`.

parent

  Control the location of this package in the configuration hierarchy.

requires

  List constraints that the configuration should satisfy if this package is active.

## Example

    cdl_package CYGPKG_INFRA {
        display       "Infrastructure"
        include_dir   cyg/infra
        description   "
            Common types and useful macros.
            Tracing and assertion facilities.
            Package startup options."

        compile startup.cxx prestart.cxx pkgstart.cxx userstart.cxx      \
                dummyxxmain.cxx null.cxx simple.cxx fancy.cxx buffer.cxx \
                diag.cxx tcdiag.cxx memcpy.c memset.c delete.cxx
    }

## See Also

Command `cdl_option`, command `cdl_component`, command `cdl_interface`.

Prev | Home | Next
`cdl_component` | Up | `cdl_interface`