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 Section 2.3, “Package Contents and Layout”.

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.