reference.sgml

ecos实时嵌入式操作系统

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 component.
</para></listitem></varlistentry>

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

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

<varlistentry><term><link linkend="ref.flavor">&flavor;</link></term>
<listitem><para>
Specify the nature of this component.
</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 component 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 component.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.make">&make;</link></term>
<listitem><para>
An additional custom build step associated with this component, 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 component, 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 component 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 component is
active and enabled.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.script">&script;</link></term>
<listitem><para>
Include additional configuration information from another
CDL script
</para></listitem></varlistentry>

</variablelist>

</refsect1>

<refsect1><title>Example</title>
<para>
<programlisting format="linespecific" width=72>
cdl_component CYGDBG_USE_ASSERTS {
    display       "Use asserts"
    default_value 1
    description   "
        If this component is enabled, assertions in the code are
        tested at run-time. Assert functions (CYG_ASSERT()) are
        defined in 'include/cyg/infra/cyg_ass.h' within the 'install'
        tree. If the component is disabled, these result in no
        additional object code and no checking of the asserted
        conditions."
    script        assert.cdl
}
</programlisting>
</para>
</refsect1>

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

</refentry>

<!-- }}} -->
<!-- {{{ cdl_package    -->

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

<refnamediv>
<refname>Command &cdl-package;</refname>
<refpurpose>Define a package, a component that can be distributed</refpurpose>
</refnamediv>

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

<refsect1><title>Description</title>
<para>
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.
</para>
<para>
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.
</para>
<para>
The following properties cannot be used in the body of a &cdl-package;
command:
</para>
<variablelist TermLength=16>

<varlistentry><term>&flavor;</term>
<listitem><para>
Packages always have the flavor <literal>booldata</literal>.
</para></listitem></varlistentry>

<varlistentry><term>&default-value;</term>
<listitem><para>
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.
</para></listitem></varlistentry>

<varlistentry><term>&legal-values;</term>
<listitem><para>
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.
</para></listitem></varlistentry>

<varlistentry><term>&calculated;</term>
<listitem><para>
The value of a package is always selected at the time that it is
loaded into the configuration, and cannot be re-calculated afterwards.
</para></listitem></varlistentry>

<varlistentry><term>&script;</term>
<listitem><para>
This would be redundant since the CDL script containing the
&cdl-package; command acts as that package's script.
</para></listitem></varlistentry>

</variablelist>

<para>
&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 <xref
linkend="package.contents">.
</para>
<para>
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:
</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 package.
</para></listitem></varlistentry>

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

<varlistentry><term><link linkend="ref.cdl-option">&cdl-option;</link></term>
<listitem><para>
Define an option which should appear immediately below
this package 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 for this package.
</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 package's configuration header file.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.define-format">&define-format;</link></term>
<listitem><para>
Control how the package's value will appear in the global
configuration header file <filename
class="headerfile">pkgconf/system.h</filename>
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.define-header">&define-header;</link></term>
<listitem><para>
Specify the configuration header file that will be generated for this package.
</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 component.
</para></listitem></varlistentry>

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

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

<varlistentry><term><link linkend="ref.hardware">&hardware;</link></term>
<listitem><para>
This package is tied to specific hardware.
</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 component provides one instance of a more general
interface. 
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.include-dir">&include-dir;</link></term>
<listitem><para>
Specify the desired location of this package's exported header files in
the install tree.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.include-files">&include-files;</link></term>
<listitem><para>
List the header files that are exported by this package.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.library">&library;</link></term>
<listitem><para>
Specify which library should contain the object files
generated by building this package.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.make">&make;</link></term>
<listitem><para>
An additional custom build step associated with this component, 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 component, 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 the package's
<literal>#define</literal> in the global configuration header file
<filename class="headerfile">pkgconf/system.h</filename>.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.parent">&parent;</link></term>
<listitem><para>
Control the location of this package 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 package is
active.
</para></listitem></varlistentry>


</variablelist>

</refsect1>

<refsect1><title>Example</title>
<programlisting format="linespecific" width=72>
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 \