language.properties.html

ecos源代码包

>As a special case, if the parent is the empty string then the
<SPAN
CLASS="APPLICATION"
>CDL</SPAN
> 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.</P
><P
>The <SPAN
CLASS="PROPERTY"
>script</SPAN
> property can only be used in the body of a
<TT
CLASS="LITERAL"
>cdl_component</TT
> command. The property takes a single filename as
argument, and this should be another <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> script containing
additional options, sub-components and interfaces that should go below
the current component in the hierarchy. If the <A
HREF="package.html#PACKAGE.HIERARCHY"
>directory layout conventions</A
> are
observed then the component framework will look for the specified file
relative to the <TT
CLASS="FILENAME"
>cdl</TT
>
subdirectory of the package, otherwise the filename will be treated as
relative to the package's top-level directory.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>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
}</PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="LANGUAGE.PROPERTIES.VALUE">Value-related Properties</H2
><P
>There are seven properties which are related to option values and
state: <A
HREF="ref.flavor.html"
><SPAN
CLASS="PROPERTY"
>flavor</SPAN
></A
>,
<A
HREF="ref.calculated.html"
><SPAN
CLASS="PROPERTY"
>calculated</SPAN
></A
>,
<A
HREF="ref.default-value.html"
><SPAN
CLASS="PROPERTY"
>default_value</SPAN
></A
>,
<A
HREF="ref.legal-values.html"
><SPAN
CLASS="PROPERTY"
>legal_values</SPAN
></A
>,
<A
HREF="ref.active-if.html"
><SPAN
CLASS="PROPERTY"
>active_if</SPAN
></A
>,
<A
HREF="ref.implements.html"
><SPAN
CLASS="PROPERTY"
>implements</SPAN
></A
>, and
<A
HREF="ref.requires.html"
><SPAN
CLASS="PROPERTY"
>requires</SPAN
></A
>. More detailed
information can be found in <A
HREF="language.values.html"
>the Section called <I
>Values and Expressions</I
></A
>.</P
><P
>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 <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> scripts still reference
kernel options, for example
<TT
CLASS="VARNAME"
>CYGSEM_LIBM_THREAD_SAFE_COMPAT_MODE</TT
> has a
<SPAN
CLASS="PROPERTY"
>requires</SPAN
> constraint on
<TT
CLASS="VARNAME"
>CYGVAR_KERNEL_THREADS_DATA</TT
>. 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
<TT
CLASS="VARNAME"
>CYGPKG_LIBC_STDIO</TT
> component is disabled then some
other options such as <TT
CLASS="VARNAME"
>CYGNUM_LIBC_STDIO_BUFSIZE</TT
>
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 <SPAN
CLASS="PROPERTY"
>flavor</SPAN
> property can be used to control this:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>flavor none</TT
></DT
><DD
><P
>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 <TT
CLASS="LITERAL"
>1</TT
>. 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.</P
></DD
><DT
><TT
CLASS="LITERAL"
>flavor bool</TT
></DT
><DD
><P
>Only the boolean part of the option is user-modifiable. The data part
is fixed at <TT
CLASS="LITERAL"
>1</TT
>.</P
></DD
><DT
><TT
CLASS="LITERAL"
>flavor data</TT
></DT
><DD
><P
>Only the data part of the option is user-modifiable. The boolean part
is fixed at enabled.</P
></DD
><DT
><TT
CLASS="LITERAL"
>flavor booldata</TT
></DT
><DD
><P
>Both the boolean and the data part of the option are user-modifiable.</P
></DD
></DL
></DIV
><P
>For more details of <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> flavors and how a flavor affects expression
evaluation, and other consequences, see <A
HREF="language.values.html"
>the Section called <I
>Values and Expressions</I
></A
>. The <SPAN
CLASS="PROPERTY"
>flavor</SPAN
> property cannot be used for a
package because packages always have the <TT
CLASS="LITERAL"
>booldata</TT
>
flavor. Options and components have the <TT
CLASS="LITERAL"
>bool</TT
> flavor
by default, since most configuration choices are simple yes-or-no
choices. Interfaces have the <TT
CLASS="LITERAL"
>data</TT
> flavor by default.</P
><P
>The <SPAN
CLASS="PROPERTY"
>calculated</SPAN
> property can be used for options which should not be
user-modifiable, but which instead are fixed by the target hardware or
determined from the current values of other options. In general
<SPAN
CLASS="PROPERTY"
>calculated</SPAN
> options should be avoided, since they can be confusing to
users who need to figure out whether or not a particular option can
actually be changed. There are a number of valid uses for <SPAN
CLASS="PROPERTY"
>calculated</SPAN
>
options, and quite a few invalid ones as well. The <A
HREF="ref.calculated.html"
>reference packages</A
> should be consulted
for further details. The property takes an <A
HREF="language.values.html#LANGUAGE.EXPRESSION"
>ordinary <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> expression</A
> as
argument, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
># 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
}</PRE
></TD
></TR
></TABLE
><P
>The <SPAN
CLASS="PROPERTY"
>calculated</SPAN
> property cannot be used for packages or interfaces.
The value of a package always corresponds to the version of that
package which is loaded, and this is under user control. Interfaces
are implicitly calculated, based on the number of active and enabled
implementors.</P
><P
>The <SPAN
CLASS="PROPERTY"
>default_value</SPAN
> property is similar to <SPAN
CLASS="PROPERTY"
>calculated</SPAN
>, but only
specifies a default value which users can modify. Again this property
is not relevant to packages or interfaces. A typical example would be:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>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
    &#8230;
}</PRE
></TD
></TR
></TABLE
><P
>The <SPAN
CLASS="PROPERTY"
>legal_values</SPAN
> property imposes a constraint on the possible
values of the data part of an option. Hence it is only applicable to
options with the <TT
CLASS="LITERAL"
>data</TT
> or
<TT
CLASS="LITERAL"
>booldata</TT
> flavors. It cannot be used for a package
since the only valid value for a package is its version number. The
arguments to the <SPAN
CLASS="PROPERTY"
>legal_values</SPAN
> property should constitute a <A
HREF="language.values.html#LANGUAGE.LIST-EXPRESSION"
><SPAN
CLASS="APPLICATION"
>CDL</SPAN
> list expression</A
>.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_option CYGNUM_LIBC_TIME_STD_DEFAULT_OFFSET {
    display       "Default Standard Time offset"
    flavor        data
    legal_values  -- -90000 to 90000
    default_value -- 0
    &#8230;
}</PRE
></TD
></TR
></TABLE
><P
>The <SPAN
CLASS="PROPERTY"
>active_if</SPAN
> property does not relate directly to an option's
value, but rather to its active state. Usually this is controlled via
the configuration hierarchy: if the
<TT
CLASS="VARNAME"
>CYGPKG_LIBC_STDIO</TT
> component is disabled then all
options below it are inactive and do not have any consequences.
In some cases the hierarchy does not provide sufficient control, for
example an option should only be active if two disjoint sets of
conditions are satisfied: the hierarchy could be used for one of these
conditions, and an additional <SPAN
CLASS="PROPERTY"
>active_if</SPAN
> property could be used for
the other one. The arguments to <SPAN
CLASS="PROPERTY"
>active_if</SPAN
> should constitute a
<A
HREF="language.values.html#LANGUAGE.GOAL-EXPRESSION"
><SPAN
CLASS="APPLICATION"
>CDL</SPAN
> goal expression</A
>.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
># Do not provide extra semaphore debugging if there are no semaphores
cdl_option CYGDBG_KERNEL_INSTRUMENT_BINSEM {
    active_if CYGPKG_KERNEL_SYNCH
    &#8230;
}</PRE
></TD
></TR
></TABLE
><P
>The <SPAN
CLASS="PROPERTY"
>implements</SPAN
> property is related to the concept of <A
HREF="language.interface.html"
><SPAN
CLASS="APPLICATION"
>CDL</SPAN
> interfaces</A
>. If an option is
active and enabled and it implements a particular interface then it
contributes <TT
CLASS="LITERAL"
>1</TT
> to that interface's value.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_package CYGPKG_NET_EDB7XXX_ETH_DRIVERS {
    display       "Cirrus Logic ethernet driver"
    implements    CYGHWR_NET_DRIVERS
    implements    CYGHWR_NET_DRIVER_ETH0
    &#8230;
}</PRE
></TD
></TR
></TABLE
><P
>The <SPAN
CLASS="PROPERTY"
>requires</SPAN
> property is used to impose constraints on the user's
choices. For example it is unreasonable to expect the C library to
provide thread-safe implementations of certain functions if the
underlying kernel support has been disabled, or even if the kernel is
not being used at all.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_option CYGSEM_LIBC_PER_THREAD_ERRNO {
    display       "Per-thread errno"
    doc           ref/ecos-ref.15.html
    requires      CYGVAR_KERNEL_THREADS_DATA
    default_value 1
    &#8230;
}</PRE
></TD
></TR
></TABLE
><P
>The arguments to the <SPAN
CLASS="PROPERTY"
>requires</SPAN
> property should be a <A
HREF="language.values.html#LANGUAGE.GOAL-EXPRESSION"
><SPAN
CLASS="APPLICATION"
>CDL</SPAN
> goal expression</A
>.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="LANGUAGE.PROPERTIES.DEFINE">Generating the Configuration Header Files</H2
><P
>When creating or updating a build tree the component framework will
also generate configuration header files, one per package. By default
it will generate a <TT
CLASS="LITERAL"
>#define</TT
> for each option,
component or interface that is active and enabled. For options with
the <TT
CLASS="LITERAL"
>data</TT
> or <TT
CLASS="LITERAL"
>booldata</TT
> flavors the
<TT
CLASS="LITERAL"
>#define</TT
> will use the option's data part, otherwise
it will use the constant <TT
CLASS="LITERAL"
>1</TT
>. Typical output would
include:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define CYGFUN_LIBC_TIME_POSIX 1
#define CYGNUM_LIBC_TIME_DST_DEFAULT_STATE -1</PRE
></TD
></TR
></TABLE
><P
>There are six properties which can be used to control the header file
generation process:
<A
HREF="ref.define-header.html"
><SPAN
CLASS="PROPERTY"
>define_header</SPAN
></A
>,
<A
HREF="ref.no-define.html"
><SPAN
CLASS="PROPERTY"
>no_define</SPAN
></A
>,
<A
HREF="ref.define-format.html"
><SPAN
CLASS="PROPERTY"
>define_format</SPAN
></A
>,