URL
https://opencores.org/ocsvn/or1k_old/or1k_old/trunk
Subversion Repositories or1k_old
[/] [or1k_old/] [trunk/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [language.properties.html] - Rev 1782
Compare with Previous | Blame | View Log
<!-- Copyright (C) 2003 Red Hat, Inc. -->
<!-- This material may be distributed only subject to the terms -->
<!-- and conditions set forth in the Open Publication License, v1.0 -->
<!-- or later (the latest version is presently available at -->
<!-- http://www.opencontent.org/openpub/). -->
<!-- Distribution of the work or derivative of the work in any -->
<!-- standard (paper) book form is prohibited unless prior -->
<!-- permission is obtained from the copyright holder. -->
<HTML
><HEAD
><TITLE
>CDL Properties</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="The eCos Component Writer's Guide"
HREF="cdl-guide.html"><LINK
REL="UP"
TITLE="The CDL Language"
HREF="language.html"><LINK
REL="PREVIOUS"
TITLE="CDL Commands"
HREF="language.commands.html"><LINK
REL="NEXT"
TITLE="Option Naming Convention"
HREF="language.naming.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>The <SPAN
CLASS="APPLICATION"
>eCos</SPAN
> Component Writer's Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="language.commands.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 3. The CDL Language</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="language.naming.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="LANGUAGE.PROPERTIES">CDL Properties</H1
><P
>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.</P
><P
>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 <SPAN
CLASS="PROPERTY"
>make_object</SPAN
> and <SPAN
CLASS="PROPERTY"
>include_files</SPAN
>, and are used
only rarely.</P
><P
>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 <SPAN
CLASS="PROPERTY"
>compile</SPAN
>
property which specifies the file or files that should be compiled if
a given option is active and enabled. The <SPAN
CLASS="PROPERTY"
>define_proc</SPAN
> property takes
as argument a snippet of <SPAN
CLASS="APPLICATION"
>Tcl</SPAN
> code. The <SPAN
CLASS="PROPERTY"
>active_if</SPAN
>, <SPAN
CLASS="PROPERTY"
>calculated</SPAN
>,
<SPAN
CLASS="PROPERTY"
>default_value</SPAN
>, <SPAN
CLASS="PROPERTY"
>legal_values</SPAN
> and <SPAN
CLASS="PROPERTY"
>requires</SPAN
> properties take various
expressions. Additional properties may be defined in future which take
new kinds of arguments.</P
><P
>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
<TT
CLASS="LITERAL"
>-</TT
> will be interpreted as an option, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_package CYGPKG_HAL_ARM {
…
make -priority 1 {
…
}
}</PRE
></TD
></TR
></TABLE
><P
>If the option involves additional data, as for the
<TT
CLASS="LITERAL"
>-priority</TT
> example above, then this can be written
as either <TT
CLASS="LITERAL"
>-priority=1</TT
> or as
<TT
CLASS="LITERAL"
>-priority 1</TT
>. On occasion the option parsing
code can get in the way, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_STATE {
…
legal_values -1 to 1
default_value -1
}</PRE
></TD
></TR
></TABLE
><P
>Neither the <SPAN
CLASS="PROPERTY"
>legal_values</SPAN
> nor the <SPAN
CLASS="PROPERTY"
>default_value</SPAN
> property will
accept <TT
CLASS="LITERAL"
>-1</TT
> as a valid option, so this will result in
syntax errors when the <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> script is read in by the component
framework. To avoid problems, the option parsing code will recognize
the string <TT
CLASS="LITERAL"
>--</TT
> and will not attempt to interpret any
subsequent arguments. Hence this option should be written as:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_STATE {
…
legal_values -- -1 to 1
default_value -- -1
}</PRE
></TD
></TR
></TABLE
><P
>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 <TT
CLASS="LITERAL"
>#</TT
> character can be used for
comments. The backslash character <TT
CLASS="LITERAL"
>\</TT
>, the
dollar character <TT
CLASS="LITERAL"
>$</TT
>, square brackets
<TT
CLASS="LITERAL"
>[</TT
> and <TT
CLASS="LITERAL"
>]</TT
>, braces
<TT
CLASS="LITERAL"
>{</TT
> and <TT
CLASS="LITERAL"
>}</TT
>, and the quote character
<TT
CLASS="LITERAL"
>"</TT
> 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 <SPAN
CLASS="APPLICATION"
>Tcl</SPAN
> interpreter around
performing the parser can be very powerful. For more details of
how the presence of a <SPAN
CLASS="APPLICATION"
>Tcl</SPAN
> interpreter can affect <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> scripts,
see <A
HREF="language.tcl.html"
>the Section called <I
>An Introduction to Tcl</I
></A
>.</P
><P
>Many of the properties can be used in any of <TT
CLASS="LITERAL"
>cdl_package</TT
>,
<TT
CLASS="LITERAL"
>cdl_component</TT
>, <TT
CLASS="LITERAL"
>cdl_option</TT
> or <TT
CLASS="LITERAL"
>cdl_interface</TT
>. Other properties are
more specific. The <SPAN
CLASS="PROPERTY"
>script</SPAN
> property is only relevant to components.
The <SPAN
CLASS="PROPERTY"
>define_header</SPAN
>, <SPAN
CLASS="PROPERTY"
>hardware</SPAN
>, <SPAN
CLASS="PROPERTY"
>include_dir</SPAN
>, <SPAN
CLASS="PROPERTY"
>include_files</SPAN
>, and
<SPAN
CLASS="PROPERTY"
>library</SPAN
> properties apply to a package as a whole, so can only occur
in the body of a <TT
CLASS="LITERAL"
>cdl_package</TT
> command. The <SPAN
CLASS="PROPERTY"
>calculated</SPAN
>,
<SPAN
CLASS="PROPERTY"
>default_value</SPAN
>, <SPAN
CLASS="PROPERTY"
>legal_values</SPAN
> and <SPAN
CLASS="PROPERTY"
>flavor</SPAN
> properties are not
relevant to packages, as will be explained later. The <SPAN
CLASS="PROPERTY"
>calculated</SPAN
> and
<SPAN
CLASS="PROPERTY"
>default_value</SPAN
> properties are also not relevant to interfaces.</P
><P
>This section lists the various properties, grouped by purpose. Each
property also has a full reference page in <A
HREF="reference.html"
>Chapter 5</A
>.
Properties related to values and expressions are described in more
detail in <A
HREF="language.values.html"
>the Section called <I
>Values and Expressions</I
></A
>. Properties related to
header file generation and to the build process are described in
<A
HREF="build.html"
>Chapter 4</A
>.</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="LANGUAGE.PROPERTIES.USER">Information-providing Properties</H2
><P
>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 <A
HREF="ref.display.html"
><SPAN
CLASS="PROPERTY"
>display</SPAN
></A
> property gives
a textual alias for an option, which is usually more comprehensible
than something like <TT
CLASS="LITERAL"
>CYGPKG_LIBC_TIME_ZONES`</TT
>; the
<A
HREF="ref.description.html"
><SPAN
CLASS="PROPERTY"
>description</SPAN
></A
> property gives a
longer description, typically a paragraph or so; the <A
HREF="ref.doc.html"
><SPAN
CLASS="PROPERTY"
>doc</SPAN
></A
> property specifies the location of
additional on-line documentation related to a configuration option. In
the context of a graphical tool the <SPAN
CLASS="PROPERTY"
>display</SPAN
> string will be the
primary way for users to identify configuration options; the
<SPAN
CLASS="PROPERTY"
>description</SPAN
> paragraph will be visible whenever the option is
selected; the on-line documentation will only be accessed when the
user explicitly requests it.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>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."
…
}</PRE
></TD
></TR
></TABLE
><P
>All three properties take a single argument. For <SPAN
CLASS="PROPERTY"
>display</SPAN
> and
<SPAN
CLASS="PROPERTY"
>description</SPAN
> this argument is just a string. For <SPAN
CLASS="PROPERTY"
>doc</SPAN
> it should be a
pointer to a suitable HTML file, optionally including an anchor within
that page. If the <A
HREF="package.html#PACKAGE.HIERARCHY"
>directory layout
conventions</A
> are observed then the component framework will look
for the HTML file in the package's <TT
CLASS="FILENAME"
>doc</TT
> sub-directory, otherwise the <SPAN
CLASS="PROPERTY"
>doc</SPAN
>
filename will be treated as relative to the package's top-level directory.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="LANGUAGE.PROPERTIES.HIERARCHY">The Configuration Hierarchy</H2
><P
>There are two properties related to the hierarchical organization of
components and options: <A
HREF="ref.parent.html"
><SPAN
CLASS="PROPERTY"
>parent</SPAN
></A
> and
<A
HREF="ref.script.html"
><SPAN
CLASS="PROPERTY"
>script</SPAN
></A
>.</P
><P
>The <SPAN
CLASS="PROPERTY"
>parent</SPAN
> property can be used to move a <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> 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
<TT
CLASS="VARNAME"
>CYGPKG_HAL_SH</TT
> is placed below the common HAL
package <TT
CLASS="VARNAME"
>CYGPKG_HAL</TT
> using a <SPAN
CLASS="PROPERTY"
>parent</SPAN
> property.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_package CYGPKG_HAL_SH {
display "SH architecture"
parent CYGPKG_HAL
…
}</PRE
></TD
></TR
></TABLE
><P
>The <SPAN
CLASS="PROPERTY"
>parent</SPAN
> property can also be used in the body of a
<TT
CLASS="LITERAL"
>cdl_component</TT
>, <TT
CLASS="LITERAL"
>cdl_option</TT
> or <TT
CLASS="LITERAL"
>cdl_interface</TT
>, 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.</P
><P
>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 <stdio.h>."
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
…
}</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
…
}</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
…
}</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
…
}</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
…
}</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
>,
<A
HREF="ref.define.html"
><SPAN
CLASS="PROPERTY"
>define</SPAN
></A
>,
<A
HREF="ref.if-define.html"
><SPAN
CLASS="PROPERTY"
>if_define</SPAN
></A
>, and
<A
HREF="ref.define-proc.html"
><SPAN
CLASS="PROPERTY"
>define_proc</SPAN
></A
>.</P
><P
>By default the component framework will generate a configuration
header file for each package based on the package's name: everything
up to and including the first underscore is discarded, the rest of the
name is lower-cased, and a <TT
CLASS="LITERAL"
>.h</TT
> suffix is appended.
For example the configuration header file for the kernel package
<TT
CLASS="VARNAME"
>CYGPKG_KERNEL</TT
> is <TT
CLASS="FILENAME"
>pkgconf/kernel.h</TT
>. The <SPAN
CLASS="PROPERTY"
>define_header</SPAN
>
property can be used to specify an alternative filename. This applies
to all the components and options within a package, so it can only be
used in the body of a <TT
CLASS="LITERAL"
>cdl_package</TT
> command. For example the following
specifies that the configuration header file for the SPARClite HAL
package is <TT
CLASS="FILENAME"
>pkgconf/hal_sparclite.h</TT
>.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_package CYGPKG_HAL_SPARCLITE {
display "SPARClite architecture"
parent CYGPKG_HAL
hardware
define_header hal_sparclite.h
…
}</PRE
></TD
></TR
></TABLE
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>At present the main use for the <SPAN
CLASS="PROPERTY"
>define_header</SPAN
> property is related
to hardware packages, see the <A
HREF="ref.hardware.html"
>reference
pages</A
> for more details.</P
></BLOCKQUOTE
></DIV
><P
>The <SPAN
CLASS="PROPERTY"
>no_define</SPAN
> property is used to suppress the generation of the
default <TT
CLASS="LITERAL"
>#define</TT
>. This can be useful if an option's
consequences are all related to the build process or to constraints,
and the option is never actually checked in any source code. It can
also be useful in conjunction with the <SPAN
CLASS="PROPERTY"
>define</SPAN
>, <SPAN
CLASS="PROPERTY"
>if_define</SPAN
> or
<SPAN
CLASS="PROPERTY"
>define_proc</SPAN
> properties. The <SPAN
CLASS="PROPERTY"
>no_define</SPAN
> property does not take any
arguments. </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_component CYG_HAL_STARTUP {
display "Startup type"
flavor data
legal_values { "RAM" "ROM" }
default_value {"RAM"}
no_define
define -file system.h CYG_HAL_STARTUP
…
}</PRE
></TD
></TR
></TABLE
><P
>This example also illustrates the <SPAN
CLASS="PROPERTY"
>define</SPAN
> property, which can be used
to generate a <TT
CLASS="LITERAL"
>#define</TT
> in addition to the default
one. It takes a single argument, the name of the symbol to be defined.
It also takes options to control the configuration header file in
which the symbol should be defined and the format to be used.</P
><P
>The <SPAN
CLASS="PROPERTY"
>define_format</SPAN
> property can be used to control how the value part
of the default <TT
CLASS="LITERAL"
>#define</TT
> gets formatted. For example
a format string of <TT
CLASS="LITERAL"
>"0x%04x"</TT
> could be used to
generate a four-digit hexadecimal number. </P
><P
>The <SPAN
CLASS="PROPERTY"
>if_define</SPAN
> property is intended for use primarily to control
assertions, tracing, and similar functionality. It supports a specific
implementation model for these, allowing control at the grain of
packages or even individual source files. The <A
HREF="ref.if-define.html"
>reference pages</A
> provide additional
information.</P
><P
>The <SPAN
CLASS="PROPERTY"
>define_proc</SPAN
> property provides an escape mechanism for those
cases where something special has to happen at configuration header
file generation time. It takes a single argument, a fragment of <SPAN
CLASS="APPLICATION"
>Tcl</SPAN
>
code, which gets executed when the header file is generated. This code
can output arbitrary data to the header file, or perform any other
actions that might be appropriate.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="LANGUAGE.PROPERTIES.BUILD">Controlling what gets Built</H2
><P
>There are six properties which affect the build process:
<A
HREF="ref.compile.html"
><SPAN
CLASS="PROPERTY"
>compile</SPAN
></A
>,
<A
HREF="ref.make.html"
><SPAN
CLASS="PROPERTY"
>make</SPAN
></A
>,
<A
HREF="ref.make-object.html"
><SPAN
CLASS="PROPERTY"
>make_object</SPAN
></A
>,
<A
HREF="ref.library.html"
><SPAN
CLASS="PROPERTY"
>library</SPAN
></A
>,
<A
HREF="ref.include-dir.html"
><SPAN
CLASS="PROPERTY"
>include_dir</SPAN
></A
>, and
<A
HREF="ref.include-files.html"
><SPAN
CLASS="PROPERTY"
>include_files</SPAN
></A
>.
The last three apply to a package as a whole, and can only occur in
the body of a <TT
CLASS="LITERAL"
>cdl_package</TT
> command.</P
><P
>Most of the source files that go into a package should simply be
compiled with the appropriate compiler, selected by the target
architecture, and with the appropriate flags, with an additional set
defined by the target hardware and possible modifications on a
per-package basis. The resulting object files will go into the library
<TT
CLASS="FILENAME"
>libtarget.a</TT
>, which can then be linked against
application code. The <SPAN
CLASS="PROPERTY"
>compile</SPAN
> property is used to list these source
files: </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_package CYGPKG_ERROR {
display "Common error code support"
compile strerror.cxx
include_dir cyg/error
…
}</PRE
></TD
></TR
></TABLE
><P
>The arguments to the <SPAN
CLASS="PROPERTY"
>compile</SPAN
> property should be one or more source
files. Typically most of the sources will be needed for the package as
a whole, and hence they will be listed in one or more <SPAN
CLASS="PROPERTY"
>compile</SPAN
>
properties in the body of the <TT
CLASS="LITERAL"
>cdl_package</TT
>. Some sources may be
specific to particular configuration options, in other words there is
no point in compiling them unless that option is enabled, in which
case the sources should be listed in a <SPAN
CLASS="PROPERTY"
>compile</SPAN
> property in the
corresponding <TT
CLASS="LITERAL"
>cdl_option</TT
>, <TT
CLASS="LITERAL"
>cdl_component</TT
> or <TT
CLASS="LITERAL"
>cdl_interface</TT
> body.</P
><P
>Some packages may have more complicated build requirements, for
example they may involve a special target such as a linker script
which should not end up in the usual library, or they may involve
special build steps for generating an object file. The <SPAN
CLASS="PROPERTY"
>make</SPAN
> and
<SPAN
CLASS="PROPERTY"
>make_object</SPAN
> properties provide support for such requirements, for
example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_package CYGPKG_HAL_MN10300_AM33 {
display "MN10300 AM33 variant"
…
make {
<PREFIX>/lib/target.ld: <PACKAGE>/src/mn10300_am33.ld
$(CC) -E -P -Wp,-MD,target.tmp -DEXTRAS=1 -xc $(INCLUDE_PATH) \
$(CFLAGS) -o $@ $<
@echo $@ ": \\" > $(notdir $@).deps
@tail +2 target.tmp >> $(notdir $@).deps
@echo >> $(notdir $@).deps
@rm target.tmp
}
}</PRE
></TD
></TR
></TABLE
><P
>For full details of custom build steps and the build process
generally, see <A
HREF="build.html"
>Chapter 4</A
>.</P
><P
>By default all object files go into the library
<TT
CLASS="FILENAME"
>libtarget.a</TT
>. It is possible to override this at
the package level using the <SPAN
CLASS="PROPERTY"
>library</SPAN
> property, but this should be
avoided since it complicates application development: instead of just
linking with a single library for all <SPAN
CLASS="APPLICATION"
>eCos</SPAN
>-related packages, it
suddenly becomes necessary to link with several libraries.</P
><P
>The <SPAN
CLASS="PROPERTY"
>include_dir</SPAN
> and <SPAN
CLASS="PROPERTY"
>include_files</SPAN
> properties relate to a package's
exported header files. By default a package's header files will be
exported to the <TT
CLASS="FILENAME"
>install/include</TT
>
directory. This is the desired behavior for some packages like the C
library, since headers like <TT
CLASS="FILENAME"
>stdio.h</TT
> should exist at that level.
However if all header files were to end up in that directory then
there would be a significant risk of a name clash. Instead it is
better for packages to specify some sub-directory for their exported
header files, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_package CYGPKG_INFRA {
display "Infrastructure"
include_dir cyg/infra
…
}</PRE
></TD
></TR
></TABLE
><P
>The various header files exported by the infrastructure, for example
<TT
CLASS="FILENAME"
>cyg_ass.h</TT
> and <TT
CLASS="FILENAME"
>cyg_trac.h</TT
> will now end up in the
<TT
CLASS="FILENAME"
>install/include/cyg/infra</TT
>
sub-directory, where a name clash is very unlikely.</P
><P
>For packages which follow the <A
HREF="package.html#PACKAGE.HIERARCHY"
>directory layout conventions</A
> the
component framework will assume that the package's
<TT
CLASS="FILENAME"
>include</TT
> sub-directory contains
all exported header files. If this is not the case, for example
because the package is sufficiently simple that the layout convention
is inappropriate, then the exported header files can be listed
explicitly in an <SPAN
CLASS="PROPERTY"
>include_files</SPAN
> property.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="LANGUAGE.PROPERTIES.MISCELLANEOUS">Miscellaneous Properties</H2
><P
>The <A
HREF="ref.hardware.html"
><SPAN
CLASS="PROPERTY"
>hardware</SPAN
></A
> property is
only relevant to packages. Some packages such as device drivers and
HAL packages are hardware-specific, and generally it makes no sense to
add such packages to a configuration unless the corresponding hardware
is present on your target system. Typically hardware package selection
happens automatically when you select your target. The <SPAN
CLASS="PROPERTY"
>hardware</SPAN
>
property should be used to identify a hardware-specific package, and
does not take any arguments.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_package CYGPKG_HAL_MIPS {
display "MIPS architecture"
parent CYGPKG_HAL
hardware
include_dir cyg/hal
define_header hal_mips.h
…
}</PRE
></TD
></TR
></TABLE
><P
>At present the <SPAN
CLASS="PROPERTY"
>hardware</SPAN
> property is largely ignored by the component
framework. This may change in future releases.</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="language.commands.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="cdl-guide.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="language.naming.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>CDL Commands</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="language.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Option Naming Convention</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>