reference.sgml

ecos实时嵌入式操作系统

to say: &ldquo;if option <literal>A</literal> is enabled then compile
file <filename>x.c</filename>, otherwise compile file
<filename>y.c</filename>. There are two simple ways of achieving this: 
</para>
<itemizedlist>
<listitem><para>
Always compile <filename>y.c</filename>, typically by listing it in
the body of the &cdl-package;, but use
<literal>#ifndef&nbsp;A</literal> to produce an empty object file if
option <literal>A</literal> is not enabled. This has the big
disadvantage that the file always gets compiled and hence for some
configurations builds will take longer than necessary.
</para></listitem>
<listitem><para>
Use a &calculated; option whose value is <literal>!A</literal>, and
have a <literal>compile&nbsp;y.c</literal> property in its body. This
has the big disadvantage of adding another calculated option to the
configuration.
</para></listitem>
</itemizedlist>
<para>
It is likely that this will be resolved in the future, possibly by
using some sort of expression as the argument to a &compile; property.
</para>
</note>

<note>
<para>
Currently it is not possible to control the priority of a &compile;
property, in other words the order in which a file gets compiled
relative to other build steps. This functionality might prove useful
for complicated packages and should be added.
</para>
</note>
</refsect1>

<refsect1><title>Example</title>
<programlisting 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 memcpy.c memset.c delete.cxx \
            diag.cxx tcdiag.cxx
}
</programlisting>
</refsect1>

<refsect1><title>See Also</title>
<para>
Properties <link linkend="ref.make">make</link>,
<link linkend="ref.make-object">make_object</link> and
<link linkend="ref.library">library</link>.
</para>
</refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ default_value  -->

<refentry id="ref.default-value">
<refmeta>
<refentrytitle>&default-value;</refentrytitle>
</refmeta>

<refnamediv>
<refname>Property &default-value;</refname>
<refpurpose>Provide a default value for this option using a CDL expression.</refpurpose>
</refnamediv>

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

<refsect1><title>Description</title>
<para>
The &default-value; property allows the initial value of a
configuration option to depend on other configuration options. The
arguments to the property should be a &CDL; expression, see
<xref linkend="language.expression"> for the syntactic details.
In many cases a simple constant value will suffice, for example:
</para>
<programlisting width=72>
cdl_component CYGPKG_KERNEL_EXCEPTIONS {
    &hellip;
    default_value 1

    cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE {
        &hellip;
        default_value 0
    }
}
</programlisting>
<para>
However it is also possible for an option's default value to depend on
other options. For example the common HAL package provides some
support functions that are needed by the &eCos; kernel, but are
unlikely to be useful if the kernel is not being used. This
relationship can be expressed using:
</para>
<programlisting width=72>
cdl_option CYGFUN_HAL_COMMON_KERNEL_SUPPORT {
    ...
    default_value CYGPKG_KERNEL
}
</programlisting>
<para>
If the kernel is loaded then this HAL option is automatically enabled,
although the user can still disable it explicitly should this prove
necessary. If the kernel is not loaded then the option is disabled,
although it can still be enabled by the user if desired.
&default-value; expressions can be more complicated than this if
appropriate, and provide a very powerful facility for component
writers who want their code to &ldquo;just do the right thing&rdquo;
in a wide variety of configurations.
</para>
<para>
The &CDL; configuration system evaluates the &default-value;
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 &default-value;
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 by default, 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 default value of the option is the result of evaluating the
expression.
</para></listitem></varlistentry>

</variablelist>

<para>
A &cdl-option; or other entity can have at most one &default-value;
property, and it is illegal to have both a &calculated; and a
&default-value; property in one body. If an option does not have
either a &default-value; or a &calculated; property and it does not
have the flavor <literal>none</literal> then the configuration tools
will assume a default value expression of <literal>0</literal>.
</para>
<para>
On occasion it is useful to have a configuration option
<literal>A</literal> which has both a &requires; constraint on some
other option <literal>B</literal> and a &default-value; expression of
<literal>B</literal>. If option <literal>B</literal> is not enabled
then <literal>A</literal> will also be disabled by default and no
conflict arises. If <literal>B</literal> is enabled then
<literal>A</literal> also becomes enabled and again no conflict
arises. If a user attempts to enable <literal>B</literal> but not
<literal>A</literal> then there will be a conflict. Users should be
able to deduce that the two options are closely interlinked and should
not be manipulated independently except in very unusual circumstances.
</para>

<tip>
<para>
If the first entry in a &default-value; expression is a negative
number, for example <literal>default_value&nbsp;-1</literal> then this
can be misinterpreted as an option instead of as part of the
expression. Currently the &default-value; 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>default_value&nbsp;--&nbsp;-1</literal>
</para>
</tip>

<note>
<para>
In many cases it would be useful to calculate default values using
some global preferences, for example:
</para>
<programlisting width=72>
cdl_option CYGIMP_LIBC_STRING_PREFER_SMALL_TO_FAST {
    &hellip;
    default_value CYGGLO_CODESIZE > CYGGLO_SPEED
}
</programlisting>
<para>
Such global preference options do not yet exist, but are likely to be
added in a future version.
</para>
</note>

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

</refsect1>

<refsect1><title>Example</title>
<programlisting width=72>
cdl_option CYGDBG_HAL_DEBUG_GDB_THREAD_SUPPORT {
    display       "Include GDB multi-threading debug support"
    requires      CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
    default_value CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
    description   "
        This option enables some extra HAL code which is needed
        to support multi-threaded source level debugging."
}
</programlisting>
</refsect1>

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

</refentry>

<!-- }}} -->
<!-- {{{ define         -->

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

<refnamediv>
<refname>Property &define;</refname>
<refpurpose>Specify additional <literal>#define</literal> symbols that
should go into the owning package's configuration header file.</refpurpose>
</refnamediv>

<refsynopsisdiv>
<synopsis>
cdl_option &lt;name&gt; {
    define [-file=&lt;filename&gt;] [-format=&lt;format&gt;] &lt;symbol&gt;
    &hellip;
}
</synopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
Normally the configuration system generates a single
<literal>#define</literal> for each option that is active and enabled,
with the defined symbol being the name of the option. These
<literal>#define's</literal> go to the package's own configuration
header file, for example <filename class="HeaderFile">pkgconf/kernel.h</filename>
for kernel configuration options. For the majority of options this is
sufficient. Sometimes it is useful to have more control over which
<literal>#define's</literal> get generated.
</para>
<para>
The &define; property can be used to generate an addition
<literal>#define</literal> if the option is both active and enabled,
for example:
</para>
<programlisting width=72>
cdl_option CYGNUM_LIBC_STDIO_FOPEN_MAX {
    &hellip;
    define FOPEN_MAX
}
</programlisting>
<para>
If this option is given the value 40 then the following
<literal>#define's</literal> will be generated in the configuration
header <filename class="HeaderFile">pkgconf/libc.h</filename>:
</para>
<screen width=72>
#define CYGNUM_LIBC_STDIO_FOPEN_MAX 40
#define FOPEN_MAX 40
</screen>
<para>
The default <literal>#define</literal> can be suppressed if desired
using the &no-define; property. This is useful if the symbol should
only be defined in
<filename class="HeaderFile">pkgconf/system.h</filename> and not in
the package's own configuration header file. The value that will be
used for this <literal>#define</literal> is the same as for the
default one, and depends on the option's flavor as follows:
</para>

<variablelist TermLength=16>

<varlistentry><term><literal>flavor none</literal></term>
<listitem><para>
Options with this flavor are always enabled and have no value, so the
constant <literal>1</literal> will be used.
</para></listitem></varlistentry>

<varlistentry><term><literal>flavor bool</literal></term>
<listitem><para>
If the option is disabled then no <literal>#define</literal> will be
generated. Otherwise the constant <literal>1</literal> will be used.
</para></listitem></varlistentry>

<varlistentry><term><literal>flavor booldata</literal></term>
<listitem><para>
If the option is disabled then no <literal>#define</literal> will be
generated. Otherwise the option's current value will be used.
</para></listitem></varlistentry>

<varlistentry><term><literal>flavor data</literal></term>
<listitem><para>
The option's current value will be used.
</para></listitem></varlistentry>

</variablelist>

<para>
For active options with the <literal>data</literal> flavor, and for
active and enabled options with the <literal>booldata</literal>
flavor, either one or two <literal>#define's</literal> will be
generated. These take the following forms:
</para>
<programlisting width=72>
#define &lt;symbol&gt; &lt;value&gt;
#define &lt;symbol&gt;_&lt;value&gt;
</programlisting>
<para>
For the first <literal>#define</literal> it is possible to control the
format used for the value using a
<literal>-format=&lt;format&gt;</literal> option. For example, the
following can be used to output some configuration data as a C string:
</para>
<programlisting width=72>
cdl_option &lt;name&gt; {