+++ /dev/null
-<!-- 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
->
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff