reference.sgml

ecos实时嵌入式操作系统

<!-- {{{ Banner         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     reference.sgml                                              -->
<!--                                                                 -->
<!--     The man pages.                                              -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 2000, 2001, 2002 Red Hat, Inc.                    -->
<!--                                                                 -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!--                                                                 -->      
<!-- ####COPYRIGHTEND####                                            -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- Author(s):   bartv                                              -->
<!-- Contact(s):  bartv                                              -->
<!-- Date:        2000/02/06                                         -->
<!-- Version:     0.01                                               -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<chapter id="reference">
<title>CDL Language Specification</title>

<para>
This chapter contains reference information for the main &CDL;
commands &cdl-option;, &cdl-component;, &cdl-package; and
&cdl-interface;, followed by the various properties such as
&active-if; and &compile; in alphabetical order.
</para>

<!-- {{{ cdl_option     -->

<refentry id="ref.cdl-option">
<refmeta>
<refentrytitle>&cdl-option;</refentrytitle>
</refmeta>

<refnamediv>
<refname>Command &cdl-option;</refname>
<refpurpose>Define a single configuration option</refpurpose>
</refnamediv>

<refsynopsisdiv>
<synopsis>
cdl_option &lt;name&gt; {
    &hellip;
}
</synopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
The option is the basic unit of configurability. Generally each option
corresponds to a single user choice. Typically there is a certain
amount of information associated with an option to assist the user in
manipulating that option, for example a textual description. There
will also be some limits on the possible values that the user can
choose, so an option may be a simple yes-or-no choice or it may be
something more complicated such as an array size or a device name.
Options may have associated constraints, so if that option is enabled
then certain conditions have to satisfied elsewhere in the
configuration. Options usually have direct consequences such as
preprocessor <literal>#define</literal> symbols in a configuration
header file.
</para>
<para>
&cdl-option; 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.
Within a single configuration, names must be unique. If a
configuration contained two packages which defined the same entity
<literal>CYGIMP_SOME_OPTION</literal>, any references to that entity
in a &requires; property or any other expression
would be ambiguous. It is possible for a given name to be used by two
different packages if those packages should never be loaded into a
single configuration. For example, architectural HAL packages are
allowed to re-use names because a single configuration cannot target
two different architectures. For a recommended naming convention see
<xref linkend="package.contents">.
</para>
<para>
The second argument to <literal>cdl_option</literal> is a body of
properties, 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-option;. The valid properties are:
</para>

<variablelist TermLength=16>

<varlistentry><term><link linkend="ref.active-if">&active-if;</link></term>
<listitem><para>
Allow additional control over the active state of this option.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.calculated">&calculated;</link></term>
<listitem><para>
The option's value is not directly user-modifiable, it is calculated
using a suitable CDL expression.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.compile">&compile;</link></term>
<listitem><para>
List the source files that should be built if this option is active
and enabled.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.default-value">&default-value;</link></term>
<listitem><para>
Provide a default value for this option using a CDL expression.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.define">&define;</link></term>
<listitem><para>
Specify additional <literal>#define</literal> symbols that should go
into the owning package's configuration header file.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.define-format">&define-format;</link></term>
<listitem><para>
Control how the option's value will appear in the configuration header
file.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.define-proc">&define-proc;</link></term>
<listitem><para>
Use a fragment of Tcl code to output additional data to
configuration header files.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.description">&description;</link></term>
<listitem><para>
Provide a textual description for this option.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.display">&display;</link></term>
<listitem><para>
Provide a short string describing this option.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.doc">&doc;</link></term>
<listitem><para>
The location of on-line documentation for this option.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.flavor">&flavor;</link></term>
<listitem><para>
Specify the nature of this option.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.if-define">&if-define;</link></term>
<listitem><para>
Output a common preprocessor construct to a configuration header file. 
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.implements">&implements;</link></term>
<listitem><para>
Enabling this option provides one instance of a more general
interface. 
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.legal-values">&legal-values;</link></term>
<listitem><para>
Impose constraints on the possible values for this option.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.make">&make;</link></term>
<listitem><para>
An additional custom build step associated with this option, resulting
in a target that should not go directly into a library.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.make-object">&make-object;</link></term>
<listitem><para>
An additional custom build step associated with this option, resulting
in an object file that should go into a library.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.no-define">&no-define;</link></term>
<listitem><para>
Suppress the normal generation of a preprocessor
<literal>#define</literal> symbol in a configuration header file.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.parent">&parent;</link></term>
<listitem><para>
Control the location of this option in the configuration hierarchy. 
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.requires">&requires;</link></term>
<listitem><para>
List constraints that the configuration should satisfy if this option is
active and enabled.
</para></listitem></varlistentry>

</variablelist>

</refsect1>

<refsect1><title>Example</title>
<programlisting format="linespecific" width=72>
cdl_option CYGDBG_INFRA_DEBUG_PRECONDITIONS {
    display       "Preconditions"
    default_value 1
    description   "
        This option allows individual control of preconditions.
        A precondition is one type of assert, which it is
        useful to control separately from more general asserts.
        The function is CYG_PRECONDITION(condition,msg)."
}
</programlisting>
</refsect1>

<refsect1><title>See Also</title>
<para>
Command <link linkend="ref.cdl-component">&cdl-component;</link>,
command <link linkend="ref.cdl-package">&cdl-package;</link>,
command <link linkend="ref.cdl-interface">&cdl-interface;</link>.
</para>
</refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ cdl_component  -->

<refentry id="ref.cdl-component">
<refmeta>
<refentrytitle>&cdl-component;</refentrytitle>
</refmeta>

<refnamediv>
<refname>Command &cdl-component;</refname>
<refpurpose>Define a component, a collection of configuration options</refpurpose>
</refnamediv>

<refsynopsisdiv>
<synopsis>
cdl_component &lt;name&gt; {
    &hellip;
}
</synopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
A component is a configuration option that can contain additional
options and sub-components. The body of a &cdl-component; can contain
the same properties as that of a &cdl-option;. There is an additional
property, &script; which allows configuration data to be split into
multiple files. It is also possible for a component body to include
&cdl-component;, &cdl-option; and &cdl-interface; entities that should
go below this component in the configuration hierarchy.
</para>
<para>
&cdl-component; 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. Within a single configuration, names must be unique. If
a configuration contained two packages which defined the same entity
<literal>CYGIMP_SOME_OPTION</literal>, any references to that entity
in a &requires; property or any other expression would be ambiguous.
It is possible for a given name to be used by two different packages
if those packages should never be loaded into a single configuration.
For example, architectural HAL packages are allowed to re-use certain
names because a single configuration cannot target two different
architectures. For a recommended naming convention see <xref
linkend="package.contents">.
</para>
<para>
The second argument to &cdl-component; 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-component;. The valid commands are:
</para>

<variablelist TermLength=16>

<varlistentry><term><link linkend="ref.active-if">&active-if;</link></term>
<listitem><para>
Allow additional control over the active state of this component.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.calculated">&calculated;</link></term>
<listitem><para>
The component's value is not directly user-modifiable, it is calculated
using a suitable CDL expression.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.cdl-component">&cdl-component</link></term>
<listitem><para>
Define a sub-component.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.cdl-interface">&cdl-interface;</link></term>
<listitem><para>
Define an interface which should appear immediately below this
component in the configuration hierarchy.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.cdl-option">&cdl-option;</link></term>
<listitem><para>
Define a configuration option which should appear immediately below
this component in the configuration hierarchy.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.compile">&compile;</link></term>
<listitem><para>
List the source files that should be built if this component is active
and enabled.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.default-value">&default-value;</link></term>
<listitem><para>
Provide a default value for this component using a CDL expression.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.define">&define;</link></term>
<listitem><para>
Specify additional <literal>#define</literal> symbols that should go
into the owning package's configuration header file.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.define-format">&define-format;</link></term>
<listitem><para>
Control how the component's value will appear in the configuration header
file.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.define-proc">&define-proc;</link></term>
<listitem><para>