doc/html/cdl-guide/ref.cdl-option.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >cdl_option</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="The eCos Component Writer's Guide"
  20 HREF="cdl-guide.html"><LINK
  21 REL="UP"
  22 TITLE="CDL Language Specification"
  23 HREF="reference.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="CDL Language Specification"
  26 HREF="reference.html"><LINK
  27 REL="NEXT"
  28 TITLE="cdl_component"
  29 HREF="ref.cdl-component.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >The <SPAN
  50 CLASS="APPLICATION"
  51 >eCos</SPAN
  52 > Component Writer's Guide</TH
  53 ></TR
  54 ><TR
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="bottom"
  59 ><A
  60 HREF="reference.html"
  61 ACCESSKEY="P"
  62 >Prev</A
  63 ></TD
  64 ><TD
  65 WIDTH="80%"
  66 ALIGN="center"
  67 VALIGN="bottom"
  68 ></TD
  69 ><TD
  70 WIDTH="10%"
  71 ALIGN="right"
  72 VALIGN="bottom"
  73 ><A
  74 HREF="ref.cdl-component.html"
  75 ACCESSKEY="N"
  76 >Next</A
  77 ></TD
  78 ></TR
  79 ></TABLE
  80 ><HR
  81 ALIGN="LEFT"
  82 WIDTH="100%"></DIV
  83 ><H1
  84 ><A
  85 NAME="REF.CDL-OPTION"><TT
  86 CLASS="LITERAL"
  87 >cdl_option</TT
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN2940"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Command <TT
  97 CLASS="LITERAL"
  98 >cdl_option</TT
  99 >&nbsp;--&nbsp;Define a single configuration option</DIV
 100 ><DIV
 101 CLASS="REFSYNOPSISDIV"
 102 ><A
 103 NAME="AEN2944"><H2
 104 >Synopsis</H2
 105 ><TABLE
 106 BORDER="5"
 107 BGCOLOR="#E0E0F0"
 108 WIDTH="70%"
 109 ><TR
 110 ><TD
 111 ><PRE
 112 CLASS="SYNOPSIS"
 113 >cdl_option &lt;name&gt; {
 114     &#8230;
 115 }</PRE
 116 ></TD
 117 ></TR
 118 ></TABLE
 119 ></DIV
 120 ><DIV
 121 CLASS="REFSECT1"
 122 ><A
 123 NAME="AEN2946"
 124 ></A
 125 ><H2
 126 >Description</H2
 127 ><P
 128 >The option is the basic unit of configurability. Generally each option
 129 corresponds to a single user choice. Typically there is a certain
 130 amount of information associated with an option to assist the user in
 131 manipulating that option, for example a textual description. There
 132 will also be some limits on the possible values that the user can
 133 choose, so an option may be a simple yes-or-no choice or it may be
 134 something more complicated such as an array size or a device name.
 135 Options may have associated constraints, so if that option is enabled
 136 then certain conditions have to satisfied elsewhere in the
 137 configuration. Options usually have direct consequences such as
 138 preprocessor <TT
 139 CLASS="LITERAL"
 140 >#define</TT
 141 > symbols in a configuration
 142 header file.</P
 143 ><P
 144 ><TT
 145 CLASS="LITERAL"
 146 >cdl_option</TT
 147 > is implemented as a Tcl command that takes two arguments,
 148 a name and a body. The name must be a valid C preprocessor identifier:
 149 a sequence of upper or lower case letters, digits or underscores,
 150 starting with a non-digit character; identifiers beginning with an
 151 underscore should normally be avoided because they may clash with
 152 system packages or with identifiers reserved for use by the compiler.
 153 Within a single configuration, names must be unique. If a
 154 configuration contained two packages which defined the same entity
 155 <TT
 156 CLASS="LITERAL"
 157 >CYGIMP_SOME_OPTION</TT
 158 >, any references to that entity
 159 in a <SPAN
 160 CLASS="PROPERTY"
 161 >requires</SPAN
 162 > property or any other expression
 163 would be ambiguous. It is possible for a given name to be used by two
 164 different packages if those packages should never be loaded into a
 165 single configuration. For example, architectural HAL packages are
 166 allowed to re-use names because a single configuration cannot target
 167 two different architectures. For a recommended naming convention see
 168 <A
 169 HREF="package.contents.html"
 170 >the Section called <I
 171 >Package Contents and Layout</I
 172 > in Chapter 2</A
 173 >.</P
 174 ><P
 175 >The second argument to <TT
 176 CLASS="LITERAL"
 177 >cdl_option</TT
 178 > is a body of
 179 properties, typically surrounded by braces so that the Tcl interpreter
 180 treats it as a single argument. This body will be processed by a
 181 recursive invocation of the Tcl interpreter, extended with additional
 182 commands for the various properties that are allowed inside a
 183 <TT
 184 CLASS="LITERAL"
 185 >cdl_option</TT
 186 >. The valid properties are:</P
 187 ><P
 188 ></P
 189 ><DIV
 190 CLASS="VARIABLELIST"
 191 ><DL
 192 ><DT
 193 ><A
 194 HREF="ref.active-if.html"
 195 ><SPAN
 196 CLASS="PROPERTY"
 197 >active_if</SPAN
 198 ></A
 199 ></DT
 200 ><DD
 201 ><P
 202 >Allow additional control over the active state of this option.</P
 203 ></DD
 204 ><DT
 205 ><A
 206 HREF="ref.calculated.html"
 207 ><SPAN
 208 CLASS="PROPERTY"
 209 >calculated</SPAN
 210 ></A
 211 ></DT
 212 ><DD
 213 ><P
 214 >The option's value is not directly user-modifiable, it is calculated
 215 using a suitable CDL expression.</P
 216 ></DD
 217 ><DT
 218 ><A
 219 HREF="ref.compile.html"
 220 ><SPAN
 221 CLASS="PROPERTY"
 222 >compile</SPAN
 223 ></A
 224 ></DT
 225 ><DD
 226 ><P
 227 >List the source files that should be built if this option is active
 228 and enabled.</P
 229 ></DD
 230 ><DT
 231 ><A
 232 HREF="ref.default-value.html"
 233 ><SPAN
 234 CLASS="PROPERTY"
 235 >default_value</SPAN
 236 ></A
 237 ></DT
 238 ><DD
 239 ><P
 240 >Provide a default value for this option using a CDL expression.</P
 241 ></DD
 242 ><DT
 243 ><A
 244 HREF="ref.define.html"
 245 ><SPAN
 246 CLASS="PROPERTY"
 247 >define</SPAN
 248 ></A
 249 ></DT
 250 ><DD
 251 ><P
 252 >Specify additional <TT
 253 CLASS="LITERAL"
 254 >#define</TT
 255 > symbols that should go
 256 into the owning package's configuration header file.</P
 257 ></DD
 258 ><DT
 259 ><A
 260 HREF="ref.define-format.html"
 261 ><SPAN
 262 CLASS="PROPERTY"
 263 >define_format</SPAN
 264 ></A
 265 ></DT
 266 ><DD
 267 ><P
 268 >Control how the option's value will appear in the configuration header
 269 file.</P
 270 ></DD
 271 ><DT
 272 ><A
 273 HREF="ref.define-proc.html"
 274 ><SPAN
 275 CLASS="PROPERTY"
 276 >define_proc</SPAN
 277 ></A
 278 ></DT
 279 ><DD
 280 ><P
 281 >Use a fragment of Tcl code to output additional data to
 282 configuration header files.</P
 283 ></DD
 284 ><DT
 285 ><A
 286 HREF="ref.description.html"
 287 ><SPAN
 288 CLASS="PROPERTY"
 289 >description</SPAN
 290 ></A
 291 ></DT
 292 ><DD
 293 ><P
 294 >Provide a textual description for this option.</P
 295 ></DD
 296 ><DT
 297 ><A
 298 HREF="ref.display.html"
 299 ><SPAN
 300 CLASS="PROPERTY"
 301 >display</SPAN
 302 ></A
 303 ></DT
 304 ><DD
 305 ><P
 306 >Provide a short string describing this option.</P
 307 ></DD
 308 ><DT
 309 ><A
 310 HREF="ref.doc.html"
 311 ><SPAN
 312 CLASS="PROPERTY"
 313 >doc</SPAN
 314 ></A
 315 ></DT
 316 ><DD
 317 ><P
 318 >The location of on-line documentation for this option.</P
 319 ></DD
 320 ><DT
 321 ><A
 322 HREF="ref.flavor.html"
 323 ><SPAN
 324 CLASS="PROPERTY"
 325 >flavor</SPAN
 326 ></A
 327 ></DT
 328 ><DD
 329 ><P
 330 >Specify the nature of this option.</P
 331 ></DD
 332 ><DT
 333 ><A
 334 HREF="ref.if-define.html"
 335 ><SPAN
 336 CLASS="PROPERTY"
 337 >if_define</SPAN
 338 ></A
 339 ></DT
 340 ><DD
 341 ><P
 342 >Output a common preprocessor construct to a configuration header file. </P
 343 ></DD
 344 ><DT
 345 ><A
 346 HREF="ref.implements.html"
 347 ><SPAN
 348 CLASS="PROPERTY"
 349 >implements</SPAN
 350 ></A
 351 ></DT
 352 ><DD
 353 ><P
 354 >Enabling this option provides one instance of a more general
 355 interface. </P
 356 ></DD
 357 ><DT
 358 ><A
 359 HREF="ref.legal-values.html"
 360 ><SPAN
 361 CLASS="PROPERTY"
 362 >legal_values</SPAN
 363 ></A
 364 ></DT
 365 ><DD
 366 ><P
 367 >Impose constraints on the possible values for this option.</P
 368 ></DD
 369 ><DT
 370 ><A
 371 HREF="ref.make.html"
 372 ><SPAN
 373 CLASS="PROPERTY"
 374 >make</SPAN
 375 ></A
 376 ></DT
 377 ><DD
 378 ><P
 379 >An additional custom build step associated with this option, resulting
 380 in a target that should not go directly into a library.</P
 381 ></DD
 382 ><DT
 383 ><A
 384 HREF="ref.make-object.html"
 385 ><SPAN
 386 CLASS="PROPERTY"
 387 >make_object</SPAN
 388 ></A
 389 ></DT
 390 ><DD
 391 ><P
 392 >An additional custom build step associated with this option, resulting
 393 in an object file that should go into a library.</P
 394 ></DD
 395 ><DT
 396 ><A
 397 HREF="ref.no-define.html"
 398 ><SPAN
 399 CLASS="PROPERTY"
 400 >no_define</SPAN
 401 ></A
 402 ></DT
 403 ><DD
 404 ><P
 405 >Suppress the normal generation of a preprocessor
 406 <TT
 407 CLASS="LITERAL"
 408 >#define</TT
 409 > symbol in a configuration header file.</P
 410 ></DD
 411 ><DT
 412 ><A
 413 HREF="ref.parent.html"
 414 ><SPAN
 415 CLASS="PROPERTY"
 416 >parent</SPAN
 417 ></A
 418 ></DT
 419 ><DD
 420 ><P
 421 >Control the location of this option in the configuration hierarchy. </P
 422 ></DD
 423 ><DT
 424 ><A
 425 HREF="ref.requires.html"
 426 ><SPAN
 427 CLASS="PROPERTY"
 428 >requires</SPAN
 429 ></A
 430 ></DT
 431 ><DD
 432 ><P
 433 >List constraints that the configuration should satisfy if this option is
 434 active and enabled.</P
 435 ></DD
 436 ></DL
 437 ></DIV
 438 ></DIV
 439 ><DIV
 440 CLASS="REFSECT1"
 441 ><A
 442 NAME="AEN3075"
 443 ></A
 444 ><H2
 445 >Example</H2
 446 ><TABLE
 447 BORDER="5"
 448 BGCOLOR="#E0E0F0"
 449 WIDTH="70%"
 450 ><TR
 451 ><TD
 452 ><PRE
 453 CLASS="PROGRAMLISTING"
 454 >cdl_option CYGDBG_INFRA_DEBUG_PRECONDITIONS {
 455     display       "Preconditions"
 456     default_value 1
 457     description   "
 458         This option allows individual control of preconditions.
 459         A precondition is one type of assert, which it is
 460         useful to control separately from more general asserts.
 461         The function is CYG_PRECONDITION(condition,msg)."
 462 }</PRE
 463 ></TD
 464 ></TR
 465 ></TABLE
 466 ></DIV
 467 ><DIV
 468 CLASS="REFSECT1"
 469 ><A
 470 NAME="AEN3078"
 471 ></A
 472 ><H2
 473 >See Also</H2
 474 ><P
 475 >Command <A
 476 HREF="ref.cdl-component.html"
 477 ><TT
 478 CLASS="LITERAL"
 479 >cdl_component</TT
 480 ></A
 481 >,
 482 command <A
 483 HREF="ref.cdl-package.html"
 484 ><TT
 485 CLASS="LITERAL"
 486 >cdl_package</TT
 487 ></A
 488 >,
 489 command <A
 490 HREF="ref.cdl-interface.html"
 491 ><TT
 492 CLASS="LITERAL"
 493 >cdl_interface</TT
 494 ></A
 495 >.</P
 496 ></DIV
 497 ><DIV
 498 CLASS="NAVFOOTER"
 499 ><HR
 500 ALIGN="LEFT"
 501 WIDTH="100%"><TABLE
 502 SUMMARY="Footer navigation table"
 503 WIDTH="100%"
 504 BORDER="0"
 505 CELLPADDING="0"
 506 CELLSPACING="0"
 507 ><TR
 508 ><TD
 509 WIDTH="33%"
 510 ALIGN="left"
 511 VALIGN="top"
 512 ><A
 513 HREF="reference.html"
 514 ACCESSKEY="P"
 515 >Prev</A
 516 ></TD
 517 ><TD
 518 WIDTH="34%"
 519 ALIGN="center"
 520 VALIGN="top"
 521 ><A
 522 HREF="cdl-guide.html"
 523 ACCESSKEY="H"
 524 >Home</A
 525 ></TD
 526 ><TD
 527 WIDTH="33%"
 528 ALIGN="right"
 529 VALIGN="top"
 530 ><A
 531 HREF="ref.cdl-component.html"
 532 ACCESSKEY="N"
 533 >Next</A
 534 ></TD
 535 ></TR
 536 ><TR
 537 ><TD
 538 WIDTH="33%"
 539 ALIGN="left"
 540 VALIGN="top"
 541 >CDL Language Specification</TD
 542 ><TD
 543 WIDTH="34%"
 544 ALIGN="center"
 545 VALIGN="top"
 546 ><A
 547 HREF="reference.html"
 548 ACCESSKEY="U"
 549 >Up</A
 550 ></TD
 551 ><TD
 552 WIDTH="33%"
 553 ALIGN="right"
 554 VALIGN="top"
 555 ><TT
 556 CLASS="LITERAL"
 557 >cdl_component</TT
 558 ></TD
 559 ></TR
 560 ></TABLE
 561 ></DIV
 562 ></BODY
 563 ></HTML
 564 >