reference.sgml

ecos实时嵌入式操作系统

inactive, graphical tools will still allow B to be manipulated and
enabled. This would result in a new conflict which may get resolved
automatically or which may need user intervention.
</para></listitem>

<listitem><para>
If there are hardware dependencies then an &active-if; condition is
usually the preferred approach. There is no point in allowing the user
to manipulate a configuration option if the corresponding
functionality cannot possibly work on the currently-selected hardware.
Much the same argument applies to coarse-grained dependencies, for
example if an option depends on the presence of a TCP/IP stack then an
<literal>active_if&nbsp;CYGPKG_NET</literal> condition is appropriate:
it may be possible to satisfy the condition, but it requires the
fairly drastic step of loading another package; further more, if the
user wanted a TCP/IP stack in the configuration then it would probably
have been loaded already. </para></listitem>

<listitem><para>
If option B exists to provide additional debugging information about
the functionality provided by A then again an &active-if; constraint
is appropriate. There is no point in letting users enable extra
debugging facilities for a feature that is not actually present.
</para></listitem>

<listitem><para>
The configuration system's inference engine will cope equally well
with &active-if; and &requires; properties. Suppose there is a
conflict because some third option depends on B. If B is
<literal>active_if&nbsp;A</literal> then the inference engine will
attempt to make A active and enabled, and then to enable B if
necessary. If B <literal>requires&nbsp;A</literal> then the inference
engine will attempt to enable B and resolve the resulting conflict by
causing A to be both active and enabled. Although the inference occurs
in a different order, in most cases the effect will be the same.
</para></listitem>

</itemizedlist>

</refsect1>

<refsect1><title>Example</title>
<programlisting width=72>
# Do not provide extra semaphore debugging if there are no semaphores
cdl_option CYGDBG_KERNEL_INSTRUMENT_BINSEM {
    active_if CYGPKG_KERNEL_SYNCH
    &hellip;
}

# Avoid another level in the configuration hierarchy
cdl_option CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INHERITANCE_SIMPLE_RELAY {
    active_if CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INHERITANCE_SIMPLE
    &hellip;
}

# Functionality that is only relevant if another package is loaded
cdl_option CYGSEM_START_UITRON_COMPATIBILITY {
    active_if CYGPKG_UITRON
    &hellip;
}

# Check that the hardware or HAL provide the appropriate functionality
cdl_option CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT {
    active_if CYGINT_HAL_DEBUG_GDB_STUBS_BREAK
    &hellip;
}
</programlisting>
</refsect1>

<refsect1><title>See Also</title>
<para>
Property <link linkend="ref.requires">&requires;</link>.
</para>
</refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ calculated     -->

<refentry id="ref.calculated">
<refmeta>
<refentrytitle>&calculated;</refentrytitle>
</refmeta>

<refnamediv>
<refname>Property &calculated;</refname>
<refpurpose>Used if the current option's value is not user-modifiable,
but is calculated using a suitable CDL expression.</refpurpose>
</refnamediv>

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

<refsect1><title>Description</title>
<para>
In some cases it is useful to have a configuration option whose value
cannot be modified directly by the user. This can be achieved using a
&calculated;, which takes a CDL expression as argument (see <xref
linkend="language.expression"> for a description of expression
syntax). The configuration system evaluates the expression when the
current package is loaded and whenever there is a change to any other
option referenced in the expression. The result depends on the
option's flavor:
</para>

<variablelist TermLength=16>

<varlistentry><term><literal>flavor none</literal></term>
<listitem><para>
Options with this flavor have no value, so the &calculated;
property is not applicable.
</para></listitem></varlistentry>

<varlistentry><term><literal>flavor bool</literal></term>
<listitem><para>
If the expression evaluates to a non-zero result the option is
enabled, otherwise it is disabled.
</para></listitem></varlistentry>

<varlistentry><term><literal>flavor booldata</literal></term>
<listitem><para>
If the result of evaluating the expression is zero then the option is
disabled, otherwise the option is enabled and its value is the result.
</para></listitem></varlistentry>

<varlistentry><term><literal>flavor data</literal></term>
<listitem><para>
The value of the option is the result of evaluating the expression.
</para></listitem></varlistentry>

</variablelist>

<para>
There are a number of valid uses for calculated options, and there are
also many cases where some other CDL facility would be more
appropriate. Valid uses of calculated options include the following:
</para>
<itemizedlist>

<listitem><para>
On some target hardware a particular feature may be user-configurable,
while on other targets it is fixed. For example some processors can
operate in either big-endian or little-endian mode, while other
processors do not provide any choice. It is possible to have an
option <literal>CYGARC_BIGENDIAN</literal> which is calculated in
some architectural HAL packages but user-modifiable in others.
</para></listitem>

<listitem><para>
Calculated options can provide an alternative way for one package to
affect the behavior of another one. Suppose a package may provide two
possible implementations, a preferred one involving self-modifying
code and a slower alternative. If the system involves a ROM bootstrap
then the slower alternative must be used, but it would be
inappropriate to modify the startup option in every HAL to impose
constraints on this package. Instead it is possible to have a
calculated option whose value is
<literal>{&nbsp;CYG_HAL_STARTUP&nbsp;==&nbsp;"ROM"&nbsp;}</literal>,
and which has appropriate consequences. Arguably this is a spurious
example, and it should be a user choice whether or not to use
self-modifying code with a &default-value; based on
<literal>CYG_HAL_STARTUP</literal>, but that is for the component
writer to decide.
</para></listitem>

<listitem><para>
Sometimes it should be possible to perform a particular test at
compile-time, for example by using a C preprocessor
<literal>#if</literal> construct. However the preprocessor has only
limited functionality, for example it cannot perform string
comparisons. CDL expressions are more powerful.
</para></listitem>

<listitem><para>
Occasionally a particular sub-expression may occur multiple times in
a CDL script. If the sub-expression is sufficiently complex then it
may be worthwhile to have a calculated option whose value is the
sub-expression, and then reference that calculated option in the
appropriate places. 
</para></listitem>

</itemizedlist>

<para>
Alternatives to using calculated options include the following:
</para>
<itemizedlist>

<listitem><para>
CDL <link linkend="language.interface">interfaces</link> are a form of
calculated option intended as an abstraction mechanism. An interface
can be used to express the concept of <emphasis>any
scheduler</emphasis>, as opposed to a specific one such as the bitmap scheduler.
</para></listitem>

<listitem><para>
If a calculated option would serve only to add additional information
to a configuration header file, it may be possible to achieve the same
effect using a <link linkend="ref.define-proc">&define-proc</link>
property or one of the other properties related to header file
generation.
</para></listitem>

</itemizedlist>

<tip>
<para>
If the first entry in a &calculated; expression is a negative
number, for example <literal>calculated&nbsp;-1</literal> then this
can be misinterpreted as an option instead of as part of the
expression. Currently the &calculated; property does not take any
options, but this may change in future. Option processing halts at the
sequence <literal>--</literal>, so the desired value can be expressed
safely using
<literal>calculated&nbsp;--&nbsp;-1</literal>
</para>
</tip>

<warning>
<para>
Some of the CDL scripts in current &eCos; releases make excessive use
of calculated options. This is partly because the recommended
alternatives were not always available at the time the scripts were
written. It is also partly because there is still some missing
functionality, for example &define-proc; properties cannot yet access
the configuration data so it may be necessary to use &calculated;
properties to access the data and perform the desired manipulation via
a &CDL; expression. New scripts should use calculated options only in
accordance with the guidelines.
</para>
</warning>

<note>
<para>
For options with the booldata flavor the current CDL syntax does not
allow the enabled flag and the value to be calculated separately.
Functionality to permit this may be added in a future release.
</para>
</note>

<note>
<para>
It has been suggested that having options which are not
user-modifiable is potentially confusing, and that a top-level
<literal>cdl_constant</literal> command should be added to the
language instead of or in addition to the &calculated; property. Such
a change is under consideration. However because the value of a
calculated option can depend on other options, it is not necessarily
constant.
</para>
</note>

</refsect1>

<refsect1><title>Example</title>
<programlisting width=72>
# A constant on some target hardware, perhaps user-modifiable on other
# targets.
cdl_option CYGNUM_HAL_RTC_PERIOD {
    display       "Real-time clock period"
    flavor        data
    calculated    12500
}
</programlisting>
</refsect1>

<refsect1><title>See Also</title>
<para>
Properties <link linkend="ref.default-value">&default-value;</link>,
<link linkend="ref.flavor">&flavor;</link> and
<link linkend="ref.legal-values">&legal-values;</link>,
</para>
</refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ compile        -->

<refentry id="ref.compile">
<refmeta>
<refentrytitle>&compile;</refentrytitle>
</refmeta>

<refnamediv>
<refname>Property &compile;</refname>
<refpurpose>List the source files that should be built if this option
is active and enabled.</refpurpose>
</refnamediv>

<refsynopsisdiv>
<synopsis>
cdl_option &lt;name&gt; {
    compile [-library=libxxx.a] &lt;list of files&gt;
    &hellip;
}
</synopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
The &compile; property allows component developers to specify source
files which should be compiled and added to one of the target
libraries. Usually each source file will end up the library
<filename>libtarget.a</filename>. It is possible for component writers
to specify an alternative library for an entire package using the
<link linkend="ref.library">&library;</link> property. Alternatively
the desired library can be specified on the &compile; line itself. For
example, to add a particular source file to the
<filename>libextras.a</filename> library the following could be used:
</para>
<programlisting width=72>
cdl_package CYGPKG_IO_SERIAL {
    &hellip;
    compile -library=libextras.a common/tty.c
}
</programlisting>
<para>
Details of the build process including such issues as compiler flags
and the order in which things happen can be found in
<xref linkend="build">. 
</para>
<para>
&compile; properties can occur in any of &cdl-option;,
&cdl-component;, &cdl-package; or &cdl-interface;. A &compile;
property has effect if and only if the entity that contains it is
active and enabled. Typically the body of a &cdl-package; will define
any source files that need to be built irrespective of individual
options, and each &cdl-component;, &cdl-option;, and &cdl-interface;
will define source files that are more specific. A single &compile;
property can list any number of source files, all destined for the
same library. A &cdl-option; or other entity can contain multiple
&compile; properties, each of which can specify a different library.
It is possible for a given source file to be specified in &compile;
properties for several different options, in which case the source
file will get built if any of these options are active and enabled.
</para>
<para>
If the package follows the <link linkend="package.hierarchy">directory
layout conventions</link> then the configuration tools will search for
the specified source files first in the
<filename class="directory">src</filename> subdirectory of the
package, then relative to the package directory itself. 
</para>

<note>
<para>
A shortcoming of the current specification of &compile; properties is
that there is no easy way to specify source files that should be built
unless an option is enabled. It would sometimes be useful to be able