URL
https://opencores.org/ocsvn/or1k_old/or1k_old/trunk
Subversion Repositories or1k_old
[/] [or1k_old/] [trunk/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [ref.cdl-option.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_option</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="CDL Language Specification"
HREF="reference.html"><LINK
REL="PREVIOUS"
TITLE="CDL Language Specification"
HREF="reference.html"><LINK
REL="NEXT"
TITLE="cdl_component"
HREF="ref.cdl-component.html"></HEAD
><BODY
CLASS="REFENTRY"
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="reference.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="ref.cdl-component.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="REF.CDL-OPTION"><TT
CLASS="LITERAL"
>cdl_option</TT
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN2940"
></A
><H2
>Name</H2
>Command <TT
CLASS="LITERAL"
>cdl_option</TT
> -- Define a single configuration option</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN2944"><H2
>Synopsis</H2
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SYNOPSIS"
>cdl_option <name> {
…
}</PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN2946"
></A
><H2
>Description</H2
><P
>The option is the basic unit of configurability. Generally each option
corresponds to a single user choice. Typically there is a certain
amount of information associated with an option to assist the user in
manipulating that option, for example a textual description. There
will also be some limits on the possible values that the user can
choose, so an option may be a simple yes-or-no choice or it may be
something more complicated such as an array size or a device name.
Options may have associated constraints, so if that option is enabled
then certain conditions have to satisfied elsewhere in the
configuration. Options usually have direct consequences such as
preprocessor <TT
CLASS="LITERAL"
>#define</TT
> symbols in a configuration
header file.</P
><P
><TT
CLASS="LITERAL"
>cdl_option</TT
> is implemented as a Tcl command that takes two arguments,
a name and a body. The name must be a valid C preprocessor identifier:
a sequence of upper or lower case letters, digits or underscores,
starting with a non-digit character; identifiers beginning with an
underscore should normally be avoided because they may clash with
system packages or with identifiers reserved for use by the compiler.
Within a single configuration, names must be unique. If a
configuration contained two packages which defined the same entity
<TT
CLASS="LITERAL"
>CYGIMP_SOME_OPTION</TT
>, any references to that entity
in a <SPAN
CLASS="PROPERTY"
>requires</SPAN
> property or any other expression
would be ambiguous. It is possible for a given name to be used by two
different packages if those packages should never be loaded into a
single configuration. For example, architectural HAL packages are
allowed to re-use names because a single configuration cannot target
two different architectures. For a recommended naming convention see
<A
HREF="package.contents.html"
>the Section called <I
>Package Contents and Layout</I
> in Chapter 2</A
>.</P
><P
>The second argument to <TT
CLASS="LITERAL"
>cdl_option</TT
> is a body of
properties, typically surrounded by braces so that the Tcl interpreter
treats it as a single argument. This body will be processed by a
recursive invocation of the Tcl interpreter, extended with additional
commands for the various properties that are allowed inside a
<TT
CLASS="LITERAL"
>cdl_option</TT
>. The valid properties are:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><A
HREF="ref.active-if.html"
><SPAN
CLASS="PROPERTY"
>active_if</SPAN
></A
></DT
><DD
><P
>Allow additional control over the active state of this option.</P
></DD
><DT
><A
HREF="ref.calculated.html"
><SPAN
CLASS="PROPERTY"
>calculated</SPAN
></A
></DT
><DD
><P
>The option's value is not directly user-modifiable, it is calculated
using a suitable CDL expression.</P
></DD
><DT
><A
HREF="ref.compile.html"
><SPAN
CLASS="PROPERTY"
>compile</SPAN
></A
></DT
><DD
><P
>List the source files that should be built if this option is active
and enabled.</P
></DD
><DT
><A
HREF="ref.default-value.html"
><SPAN
CLASS="PROPERTY"
>default_value</SPAN
></A
></DT
><DD
><P
>Provide a default value for this option using a CDL expression.</P
></DD
><DT
><A
HREF="ref.define.html"
><SPAN
CLASS="PROPERTY"
>define</SPAN
></A
></DT
><DD
><P
>Specify additional <TT
CLASS="LITERAL"
>#define</TT
> symbols that should go
into the owning package's configuration header file.</P
></DD
><DT
><A
HREF="ref.define-format.html"
><SPAN
CLASS="PROPERTY"
>define_format</SPAN
></A
></DT
><DD
><P
>Control how the option's value will appear in the configuration header
file.</P
></DD
><DT
><A
HREF="ref.define-proc.html"
><SPAN
CLASS="PROPERTY"
>define_proc</SPAN
></A
></DT
><DD
><P
>Use a fragment of Tcl code to output additional data to
configuration header files.</P
></DD
><DT
><A
HREF="ref.description.html"
><SPAN
CLASS="PROPERTY"
>description</SPAN
></A
></DT
><DD
><P
>Provide a textual description for this option.</P
></DD
><DT
><A
HREF="ref.display.html"
><SPAN
CLASS="PROPERTY"
>display</SPAN
></A
></DT
><DD
><P
>Provide a short string describing this option.</P
></DD
><DT
><A
HREF="ref.doc.html"
><SPAN
CLASS="PROPERTY"
>doc</SPAN
></A
></DT
><DD
><P
>The location of on-line documentation for this option.</P
></DD
><DT
><A
HREF="ref.flavor.html"
><SPAN
CLASS="PROPERTY"
>flavor</SPAN
></A
></DT
><DD
><P
>Specify the nature of this option.</P
></DD
><DT
><A
HREF="ref.if-define.html"
><SPAN
CLASS="PROPERTY"
>if_define</SPAN
></A
></DT
><DD
><P
>Output a common preprocessor construct to a configuration header file. </P
></DD
><DT
><A
HREF="ref.implements.html"
><SPAN
CLASS="PROPERTY"
>implements</SPAN
></A
></DT
><DD
><P
>Enabling this option provides one instance of a more general
interface. </P
></DD
><DT
><A
HREF="ref.legal-values.html"
><SPAN
CLASS="PROPERTY"
>legal_values</SPAN
></A
></DT
><DD
><P
>Impose constraints on the possible values for this option.</P
></DD
><DT
><A
HREF="ref.make.html"
><SPAN
CLASS="PROPERTY"
>make</SPAN
></A
></DT
><DD
><P
>An additional custom build step associated with this option, resulting
in a target that should not go directly into a library.</P
></DD
><DT
><A
HREF="ref.make-object.html"
><SPAN
CLASS="PROPERTY"
>make_object</SPAN
></A
></DT
><DD
><P
>An additional custom build step associated with this option, resulting
in an object file that should go into a library.</P
></DD
><DT
><A
HREF="ref.no-define.html"
><SPAN
CLASS="PROPERTY"
>no_define</SPAN
></A
></DT
><DD
><P
>Suppress the normal generation of a preprocessor
<TT
CLASS="LITERAL"
>#define</TT
> symbol in a configuration header file.</P
></DD
><DT
><A
HREF="ref.parent.html"
><SPAN
CLASS="PROPERTY"
>parent</SPAN
></A
></DT
><DD
><P
>Control the location of this option in the configuration hierarchy. </P
></DD
><DT
><A
HREF="ref.requires.html"
><SPAN
CLASS="PROPERTY"
>requires</SPAN
></A
></DT
><DD
><P
>List constraints that the configuration should satisfy if this option is
active and enabled.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN3075"
></A
><H2
>Example</H2
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_option CYGDBG_INFRA_DEBUG_PRECONDITIONS {
display "Preconditions"
default_value 1
description "
This option allows individual control of preconditions.
A precondition is one type of assert, which it is
useful to control separately from more general asserts.
The function is CYG_PRECONDITION(condition,msg)."
}</PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN3078"
></A
><H2
>See Also</H2
><P
>Command <A
HREF="ref.cdl-component.html"
><TT
CLASS="LITERAL"
>cdl_component</TT
></A
>,
command <A
HREF="ref.cdl-package.html"
><TT
CLASS="LITERAL"
>cdl_package</TT
></A
>,
command <A
HREF="ref.cdl-interface.html"
><TT
CLASS="LITERAL"
>cdl_interface</TT
></A
>.</P
></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="reference.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="ref.cdl-component.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>CDL Language Specification</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="reference.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><TT
CLASS="LITERAL"
>cdl_component</TT
></TD
></TR
></TABLE
></DIV
></BODY
></HTML
>