language.sgml

ecos实时嵌入式操作系统

        script stdio.cdl
    }
}
</programlisting>
<para>
The <varname>CYGPKG_LIBC_STDIO_FLOATING_POINT</varname> component and
the <varname>CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS</varname> option
can then be placed at the top-level of <filename>stdio.cdl</filename>.
It is possible to have some options nested in the body of a
&cdl-component; command and other options in a separate file accessed
by the &script; property. In such a case the nested options would be
processed first, and then the other script would be read in. A script
specified by a &script; property should only define new options,
components or interfaces: it should not contain any additional
properties for the current component.
</para>
<para>
It is possible for a component's &CDL; script to have a sub-component
which also has a &script; property, and so on. In practice excessive
nesting like this is rarely useful. It is also possible to ignore the
&CDL; language support for constructing hierarchies automatically and
use the &parent; property explicitly for every single option and
component. Again this is not generally useful.
</para>
<note>
<para>
At the time of writing interfaces cannot act as containers. This may
change in a future version of the component framework. If the change
is made then interfaces would support the &script; property, just like
components.
</para>
</note>

</sect1>

<!-- }}} -->
<!-- {{{ CDL properties         -->

<!-- {{{ Introit                -->

<sect1 id="language.properties">
<title>CDL Properties</title>
<para>
Each package, component, option, and interface has a body of
properties, which provide the component framework with information
about how to handle each option. For example there is a property for a
descriptive text message which can be displayed to a user who is
trying to figure out just what effect manipulating the option would
have on the target application. There is another property for the
default value, for example whether a particular option should be
enabled or disabled by default.
</para>
<para>
All of the properties are optional, it is legal to define a
configuration option which has an empty body. However some properties
are more optional than others: users will not appreciate having to
manipulate an option if they are not given any sort of description or
documentation. Other properties are intended only for very specific
purposes, for example &make-object; and &include-files;, and are used
only rarely.
</para>
<para>
Because different properties serve very different purposes, their
syntax is not as uniform as the top-level commands. Some properties
take no arguments at all. Other properties take a single argument such
as a description string, or a list of arguments such as a &compile;
property which specifies the file or files that should be compiled if
a given option is active and enabled. The &define-proc; property takes
as argument a snippet of &Tcl; code. The &active-if;, &calculated;,
&default-value;, &legal-values; and &requires; properties take various
expressions. Additional properties may be defined in future which take
new kinds of arguments.
</para>
<para>
All property parsing code supports options for every property,
although at present the majority of properties do not yet take any
options. Any initial arguments that begin with a hyphen character
<literal>-</literal> will be interpreted as an option, for example:
</para>
<programlisting width=72>
cdl_package CYGPKG_HAL_ARM {
    &hellip;
    make -priority 1 {
        &hellip;
    }
}
</programlisting>
<para>
If the option involves additional data, as for the
<literal>-priority</literal> example above, then this can be written
as either <literal>-priority=1</literal> or as
<literal>-priority&nbsp;1</literal>. On occasion the option parsing
code can get in the way, for example:
</para>
<programlisting width=72>
cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_STATE {
    &hellip;
    legal_values -1 to 1
    default_value -1
}
</programlisting>
<para>
Neither the &legal-values; nor the &default-value; property will
accept <literal>-1</literal> as a valid option, so this will result in
syntax errors when the &CDL; script is read in by the component
framework. To avoid problems, the option parsing code will recognize
the string <literal>--</literal> and will not attempt to interpret any
subsequent arguments. Hence this option should be written as:
</para>
<programlisting width=72>
cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_STATE {
    &hellip;
    legal_values  -- -1 to 1
    default_value -- -1
}
</programlisting>
<para>
The property parsing code involves a recursive invocation of the Tcl
interpreter that is used to parse the top-level commands. This means
that some characters in the body of an option will be treated
specially. The <literal>#</literal> character can be used for
comments. The backslash character <literal>\</literal>, the
dollar character <literal>$</literal>, square brackets
<literal>[</literal> and <literal>]</literal>, braces
<literal>{</literal> and <literal>}</literal>, and the quote character
<literal>"</literal> may all receive special treatment. Most of the
time this is not a problem because these characters are not useful for
most properties. On occasion having a &Tcl; interpreter around
performing the parser can be very powerful. For more details of
how the presence of a &Tcl; interpreter can affect &CDL; scripts,
see <xref linkend="language.tcl">.
</para>
<para>
Many of the properties can be used in any of &cdl-package;,
&cdl-component;, &cdl-option; or &cdl-interface;. Other properties are
more specific. The &script; property is only relevant to components.
The &define-header;, &hardware;, &include-dir;, &include-files;, and
&library; properties apply to a package as a whole, so can only occur
in the body of a &cdl-package; command. The &calculated;,
&default-value;, &legal-values; and &flavor; properties are not
relevant to packages, as will be explained later. The &calculated; and
&default-value; properties are also not relevant to interfaces.
</para>
<para>
This section lists the various properties, grouped by purpose. Each
property also has a full reference page in <xref linkend="reference">.
Properties related to values and expressions are described in more
detail in <xref linkend="language.values">. Properties related to
header file generation and to the build process are described in
<xref linkend="build">.
</para>

<!-- }}} -->
<!-- {{{ User-visible           -->

<sect2 id="language.properties.user">
<title>Information-providing Properties</title>
<para>
Users can only be expected to manipulate configuration options
sensibly if they are given sufficient information about these options.
There are three properties which serve to explain an option in plain
text: the <link linkend="ref.display">&display;</link> property gives
a textual alias for an option, which is usually more comprehensible
than something like <literal>CYGPKG_LIBC_TIME_ZONES`</literal>; the
<link linkend="ref.description">&description;</link> property gives a
longer description, typically a paragraph or so; the <link
linkend="ref.doc">&doc;</link> property specifies the location of
additional on-line documentation related to a configuration option. In
the context of a graphical tool the &display; string will be the
primary way for users to identify configuration options; the
&description; paragraph will be visible whenever the option is
selected; the on-line documentation will only be accessed when the
user explicitly requests it.
</para>
<programlisting width=72>
cdl_package CYGPKG_UITRON {
    display       "uITRON compatibility layer"
    doc           ref/ecos-ref.a.html
    description   "
        eCos supports a uITRON Compatibility Layer, providing
        full Level S (Standard) compliance with Version 3.02 of
        the uITRON Standard, plus many Level E (Extended) features.
        uITRON is the premier Japanese embedded RTOS standard."
    &hellip;
}
</programlisting>
<para>
All three properties take a single argument. For &display; and
&description; this argument is just a string. For &doc; it should be a
pointer to a suitable HTML file, optionally including an anchor within
that page. If the <link linkend="package.hierarchy">directory layout
conventions</link> are observed then the component framework will look
for the HTML file in the package's <filename
class="directory">doc</filename> sub-directory, otherwise the &doc;
filename will be treated as relative to the package's top-level directory.
</para>
</sect2>

<!-- }}} -->
<!-- {{{ Hierarchy              -->

<sect2 id="language.properties.hierarchy">
<title>The Configuration Hierarchy</title>
<para>
There are two properties related to the hierarchical organization of
components and options: <link linkend="ref.parent">&parent;</link> and
<link linkend="ref.script">&script;</link>.
</para>
<para>
The &parent; property can be used to move a &CDL; entity somewhere
else in the hierarchy. The most common use is for packages, to avoid
having all the packages appear at the top-level of the configuration
hierarchy. For example an architectural HAL package such as
<varname>CYGPKG_HAL_SH</varname> is placed below the common HAL
package <varname>CYGPKG_HAL</varname> using a &parent; property.
</para>
<programlisting width=72>
cdl_package CYGPKG_HAL_SH {
    display       "SH architecture"
    parent        CYGPKG_HAL
    &hellip;
}
</programlisting>
<para>
The &parent; property can also be used in the body of a
&cdl-component;, &cdl-option; or &cdl-interface;, but this is less
common. However care has to be taken since excessive re-parenting can
be confusing. Care also has to be taken when reparenting below some
other package that may not actually be loaded in a given
configuration, since the resulting behavior is undefined.
</para>
<para>
As a special case, if the parent is the empty string then the
&CDL; entity is placed at the root of the hierarchy. This is useful
for global preferences, default compiler flags, and other settings
that may affect every package.
</para>
<para>
The &script; property can only be used in the body of a
&cdl-component; command. The property takes a single filename as
argument, and this should be another &CDL; script containing
additional options, sub-components and interfaces that should go below
the current component in the hierarchy. If the <link
linkend="package.hierarchy">directory layout conventions</link> are
observed then the component framework will look for the specified file
relative to the <filename class="directory">cdl</filename>
subdirectory of the package, otherwise the filename will be treated as
relative to the package's top-level directory.
</para>
<programlisting width=72>
cdl_component CYGPKG_LIBC_STDIO {
    display       "Standard input/output functions"
    flavor        bool
    requires      CYGPKG_IO
    requires      CYGPKG_IO_SERIAL_HALDIAG
    default_value 1
    description   "
        This enables support for standard I/O functions from &lt;stdio.h&gt;."

    script        stdio.cdl
}
</programlisting>

</sect2>

<!-- }}} -->
<!-- {{{ Value                  -->

<sect2 id="language.properties.value">
<title>Value-related Properties</title>
<para>
There are seven properties which are related to option values and
state: <link linkend="ref.flavor">&flavor;</link>,
<link linkend="ref.calculated">&calculated;</link>,
<link linkend="ref.default-value">&default-value;</link>,
<link linkend="ref.legal-values">&legal-values;</link>,
<link linkend="ref.active-if">&active-if;</link>,
<link linkend="ref.implements">&implements;</link>, and
<link linkend="ref.requires">&requires;</link>. More detailed
information can be found in <xref linkend="language.values">.
</para>
<para>
In the context of configurability, the concept of an option's value is
somewhat non-trivial. First an option may or may not be loaded: it is
possible to build a configuration which has the math library but not
the kernel; however the math library's &CDL; scripts still reference
kernel options, for example
<varname>CYGSEM_LIBM_THREAD_SAFE_COMPAT_MODE</varname> has a
&requires; constraint on
<varname>CYGVAR_KERNEL_THREADS_DATA</varname>. Even if an option is
loaded it may or may not be active, depending on what is happening
higher up in the hierarchy: if the C library's
<varname>CYGPKG_LIBC_STDIO</varname> component is disabled then some
other options such as <varname>CYGNUM_LIBC_STDIO_BUFSIZE</varname>
become irrelevant. In addition each option has both a boolean
enabled/disabled flag and a data part. For many options only the
boolean flag is of interest, while for others only the data part is of
interest. The &flavor; property can be used to control this:
</para>
<variablelist>
<varlistentry>
<term><literal>flavor none</literal></term>
<listitem>
<para>
This flavor indicates that neither the boolean nor the data parts are
user-modifiable: the option is always enabled and the data is always
set to <literal>1</literal>. The most common use for this is to have a
component that just acts as a placeholder in the hierarchy, allowing
various options to be grouped below it.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>flavor bool</literal></term>
<listitem>
<para>
Only the boolean part of the option is user-modifiable. The data part
is fixed at <literal>1</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>flavor data</literal></term>
<listitem>
<para>
Only the data part of the option is user-modifiable. The boolean part
is fixed at enabled.