URL
https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk
Subversion Repositories openrisc_2011-10-31
[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [ref.cdl-option.html] - Rev 174
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 >