doc/html/cdl-guide/ref.flavor.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 >flavor</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="doc"
  26 HREF="ref.doc.html"><LINK
  27 REL="NEXT"
  28 TITLE="hardware"
  29 HREF="ref.hardware.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="ref.doc.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.hardware.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.FLAVOR"><SPAN
  86 CLASS="PROPERTY"
  87 >flavor</SPAN
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN4315"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Property <SPAN
  97 CLASS="PROPERTY"
  98 >flavor</SPAN
  99 >&nbsp;--&nbsp;Specify the nature of a configuration option.</DIV
 100 ><DIV
 101 CLASS="REFSYNOPSISDIV"
 102 ><A
 103 NAME="AEN4319"><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     flavor &lt;flavor&gt;
 115     &#8230;
 116 }</PRE
 117 ></TD
 118 ></TR
 119 ></TABLE
 120 ></DIV
 121 ><DIV
 122 CLASS="REFSECT1"
 123 ><A
 124 NAME="AEN4321"
 125 ></A
 126 ><H2
 127 >Description</H2
 128 ><P
 129 >The state of a <SPAN
 130 CLASS="APPLICATION"
 131 >CDL</SPAN
 132 > configuration option is a somewhat complicated
 133 concept. This state determines what happens when a build tree is
 134 generated: it controls what files get built and what
 135 <TT
 136 CLASS="LITERAL"
 137 >#define's</TT
 138 > end up in configuration header files. The
 139 state also controls the values used during expression evaluation. The
 140 key concepts are:</P
 141 ><P
 142 ></P
 143 ><OL
 144 TYPE="1"
 145 ><LI
 146 ><P
 147 >An option may or may not be loaded into the current configuration.
 148 However it is still possible for packages to reference options which
 149 are not loaded in a <SPAN
 150 CLASS="PROPERTY"
 151 >requires</SPAN
 152 > constraint or other expression. If an
 153 option is not loaded then it will have no direct effect on the build
 154 process, and <TT
 155 CLASS="LITERAL"
 156 >0</TT
 157 > will be used for expression
 158 evaluation. </P
 159 ></LI
 160 ><LI
 161 ><P
 162 >Even if an option is loaded it may still be inactive. Usually this is
 163 controlled by the option's location in the configuration hierarchy. If
 164 an option's parent is active and enabled then the option will normally
 165 be active. If the parent is either inactive or disabled then the
 166 option will be inactive. For example, if kernel timeslicing is diabled
 167 then the option <TT
 168 CLASS="LITERAL"
 169 >CYGNUM_KERNEL_SCHED_TIMESLICE_TICKS</TT
 170 >
 171 is irrelevant and must have no effect. The <SPAN
 172 CLASS="PROPERTY"
 173 >active_if</SPAN
 174 > property can be
 175 used to specify additional constraints. If an option is inactive then
 176 it will have no direct effect on the build process, in other words it
 177 will not cause any files to get built or <TT
 178 CLASS="LITERAL"
 179 >#define's</TT
 180 >
 181 to be generated. For the purposes of expression evaluation an inactive
 182 option has a value of <TT
 183 CLASS="LITERAL"
 184 >0</TT
 185 >.</P
 186 ></LI
 187 ><LI
 188 ><P
 189 >An option may be enabled or disabled. Most options are boolean in
 190 nature, for example a particular function may get inlined or it may
 191 involve a full procedure call. If an option is disabled then it has no
 192 direct effect on the build process, and for the purposes of expression
 193 evaluation it has a value of 0.</P
 194 ></LI
 195 ><LI
 196 ><P
 197 >An option may also have additional data associated with it, for
 198 example a numerical value used to control the size of an array.</P
 199 ></LI
 200 ></OL
 201 ><P
 202 >Most options are boolean in nature and do not have any additional
 203 associated data. For some options only the data part makes sense and
 204 users should be unable to manipulate the enabled/disabled part of the
 205 state. For a comparatively small number of options it makes sense to
 206 have the ability to disable that option or to enable it and associate
 207 data as well. Finally, when constructing an option hierarchy it is
 208 occasionally useful to have entities which serve only as placeholders.
 209 The <SPAN
 210 CLASS="PROPERTY"
 211 >flavor</SPAN
 212 > property can be used to control all this. There are four
 213 possible values. It should be noted that the active or inactive state
 214 of an option takes priority over the flavor: if an option is inactive
 215 then no <TT
 216 CLASS="LITERAL"
 217 >#define's</TT
 218 > will be generated and any
 219 build-related properties such as <SPAN
 220 CLASS="PROPERTY"
 221 >compile</SPAN
 222 > will be ignored.</P
 223 ><P
 224 ></P
 225 ><DIV
 226 CLASS="VARIABLELIST"
 227 ><DL
 228 ><DT
 229 >flavor&nbsp;<TT
 230 CLASS="LITERAL"
 231 >none</TT
 232 ></DT
 233 ><DD
 234 ><P
 235 >The <TT
 236 CLASS="LITERAL"
 237 >none</TT
 238 > is intended primarily for placeholder
 239 components in the hierarchy, although it can be used for other
 240 purposes. Options with this flavor are always enabled and do not have
 241 any additional data associated with them, so there is no way for users
 242 to modify the option. For the purposes of expression evaluation an
 243 option with flavor <TT
 244 CLASS="LITERAL"
 245 >none</TT
 246 > always has the value
 247 <TT
 248 CLASS="LITERAL"
 249 >1</TT
 250 >. Normal <TT
 251 CLASS="LITERAL"
 252 >#define</TT
 253 > processing
 254 will take place, so typically a single <TT
 255 CLASS="LITERAL"
 256 >#define</TT
 257 > will
 258 be generated using the option name and a value of
 259 <TT
 260 CLASS="LITERAL"
 261 >1</TT
 262 >. Similarly build-related properties such as
 263 <SPAN
 264 CLASS="PROPERTY"
 265 >compile</SPAN
 266 > will take effect.</P
 267 ></DD
 268 ><DT
 269 >flavor&nbsp;<TT
 270 CLASS="LITERAL"
 271 >bool</TT
 272 ></DT
 273 ><DD
 274 ><P
 275 >Boolean options can be either enabled or disabled, and there is no
 276 additional data associated with them. If a boolean option is disabled
 277 then no <TT
 278 CLASS="LITERAL"
 279 >#define</TT
 280 > will be generated and any
 281 build-related properties such as <SPAN
 282 CLASS="PROPERTY"
 283 >compile</SPAN
 284 > will be ignored. For the
 285 purposes of expression evaluation a disabled option has the value
 286 <TT
 287 CLASS="LITERAL"
 288 >0</TT
 289 >. If a boolean option is enabled then normal
 290 <TT
 291 CLASS="LITERAL"
 292 >#define</TT
 293 > processing will take place, all
 294 build-related properties take effect, and the option's value will be
 295 <TT
 296 CLASS="LITERAL"
 297 >1</TT
 298 >.</P
 299 ></DD
 300 ><DT
 301 >flavor&nbsp;<TT
 302 CLASS="LITERAL"
 303 >data</TT
 304 ></DT
 305 ><DD
 306 ><P
 307 >Options with this flavor are always enabled, and have some additional
 308 data associated with them which can be edited by the user. This data
 309 can be any sequence of characters, although in practice the
 310 <SPAN
 311 CLASS="PROPERTY"
 312 >legal_values</SPAN
 313 > property will often be used to impose constraints. In
 314 appropriate contexts such as expressions the configuration tools will
 315 attempt to interpret the data as integer or floating point numbers.
 316 Since an option with the <TT
 317 CLASS="LITERAL"
 318 >data</TT
 319 > flavor cannot be
 320 disabled, normal <TT
 321 CLASS="LITERAL"
 322 >#define</TT
 323 > processing takes place and
 324 the data will be used for the value. Similarly all build-related
 325 properties take effect, and the option's value for the purposes of
 326 expression evaluation is the data.</P
 327 ></DD
 328 ><DT
 329 >flavor&nbsp;<TT
 330 CLASS="LITERAL"
 331 >booldata</TT
 332 ></DT
 333 ><DD
 334 ><P
 335 >This combines the <TT
 336 CLASS="LITERAL"
 337 >bool</TT
 338 > and <TT
 339 CLASS="LITERAL"
 340 >data</TT
 341 >
 342 flavors. The option may be enabled or disabled, and in addition the
 343 option has some associated data. If the option is disabled then no
 344 <TT
 345 CLASS="LITERAL"
 346 >#define</TT
 347 > will be generated, the build-related
 348 properties have no effect, and for the purposes of expression
 349 evaluation the option's value is <TT
 350 CLASS="LITERAL"
 351 >0</TT
 352 >. If the option
 353 is enabled then a <TT
 354 CLASS="LITERAL"
 355 >#define</TT
 356 > will be generated using
 357 the data as the value, all build-related properties take effect, and
 358 the option's value for the purposes of expression evaluation is the
 359 data. If <TT
 360 CLASS="LITERAL"
 361 >0</TT
 362 > is legal data then it is not possible to
 363 distinguish this case from the option being disabled or inactive.</P
 364 ></DD
 365 ></DL
 366 ></DIV
 367 ><P
 368 >Options and components have the <TT
 369 CLASS="LITERAL"
 370 >bool</TT
 371 > flavor by
 372 default, but this can be changed as desired. Packages always have the
 373 <TT
 374 CLASS="LITERAL"
 375 >booldata</TT
 376 > flavor, and this cannot be changed.
 377 Interfaces have the <TT
 378 CLASS="LITERAL"
 379 >data</TT
 380 > flavor by default, since
 381 the value of an interface is a count of the number of active and
 382 enabled interfaces, but they can be given the <TT
 383 CLASS="LITERAL"
 384 >bool</TT
 385 >
 386 or <TT
 387 CLASS="LITERAL"
 388 >booldata</TT
 389 > flavors.</P
 390 ><DIV
 391 CLASS="NOTE"
 392 ><BLOCKQUOTE
 393 CLASS="NOTE"
 394 ><P
 395 ><B
 396 >Note: </B
 397 >The expression syntax needs to be extended to allow the loaded,
 398 active, enabled and data aspects of an option's state to be examined
 399 individually. This would allow component writers to distinguish
 400 between a disabled <TT
 401 CLASS="LITERAL"
 402 >booldata</TT
 403 > option and an enabled
 404 one which has a value of <TT
 405 CLASS="LITERAL"
 406 >0</TT
 407 >. Such an enhancement to
 408 the expression syntax may also prove useful in other circumstances.</P
 409 ></BLOCKQUOTE
 410 ></DIV
 411 ></DIV
 412 ><DIV
 413 CLASS="REFSECT1"
 414 ><A
 415 NAME="AEN4397"
 416 ></A
 417 ><H2
 418 >Example</H2
 419 ><TABLE
 420 BORDER="5"
 421 BGCOLOR="#E0E0F0"
 422 WIDTH="70%"
 423 ><TR
 424 ><TD
 425 ><PRE
 426 CLASS="PROGRAMLISTING"
 427 >&#13;cdl_component CYGPKG_LIBM_COMPATIBILITY {
 428
 429     cdl_component CYGNUM_LIBM_COMPATIBILITY {
 430         flavor booldata
 431         &#8230;
 432
 433         cdl_option CYGNUM_LIBM_COMPAT_DEFAULT {
 434             flavor data
 435             &#8230;
 436         }
 437     }
 438
 439     &#8230;
 440 }
 441
 442 cdl_component CYGPKG_LIBM_TRACE {
 443     flavor        bool
 444     &#8230;
 445 }</PRE
 446 ></TD
 447 ></TR
 448 ></TABLE
 449 ></DIV
 450 ><DIV
 451 CLASS="REFSECT1"
 452 ><A
 453 NAME="AEN4400"
 454 ></A
 455 ><H2
 456 >See Also</H2
 457 ><P
 458 >Properties <A
 459 HREF="ref.calculated.html"
 460 ><SPAN
 461 CLASS="PROPERTY"
 462 >calculated</SPAN
 463 ></A
 464 >,
 465 <A
 466 HREF="ref.default-value.html"
 467 ><SPAN
 468 CLASS="PROPERTY"
 469 >default_value</SPAN
 470 ></A
 471 > and
 472 <A
 473 HREF="ref.legal-values.html"
 474 ><SPAN
 475 CLASS="PROPERTY"
 476 >legal_values</SPAN
 477 ></A
 478 >,</P
 479 ></DIV
 480 ><DIV
 481 CLASS="NAVFOOTER"
 482 ><HR
 483 ALIGN="LEFT"
 484 WIDTH="100%"><TABLE
 485 SUMMARY="Footer navigation table"
 486 WIDTH="100%"
 487 BORDER="0"
 488 CELLPADDING="0"
 489 CELLSPACING="0"
 490 ><TR
 491 ><TD
 492 WIDTH="33%"
 493 ALIGN="left"
 494 VALIGN="top"
 495 ><A
 496 HREF="ref.doc.html"
 497 ACCESSKEY="P"
 498 >Prev</A
 499 ></TD
 500 ><TD
 501 WIDTH="34%"
 502 ALIGN="center"
 503 VALIGN="top"
 504 ><A
 505 HREF="cdl-guide.html"
 506 ACCESSKEY="H"
 507 >Home</A
 508 ></TD
 509 ><TD
 510 WIDTH="33%"
 511 ALIGN="right"
 512 VALIGN="top"
 513 ><A
 514 HREF="ref.hardware.html"
 515 ACCESSKEY="N"
 516 >Next</A
 517 ></TD
 518 ></TR
 519 ><TR
 520 ><TD
 521 WIDTH="33%"
 522 ALIGN="left"
 523 VALIGN="top"
 524 ><SPAN
 525 CLASS="PROPERTY"
 526 >doc</SPAN
 527 ></TD
 528 ><TD
 529 WIDTH="34%"
 530 ALIGN="center"
 531 VALIGN="top"
 532 ><A
 533 HREF="reference.html"
 534 ACCESSKEY="U"
 535 >Up</A
 536 ></TD
 537 ><TD
 538 WIDTH="33%"
 539 ALIGN="right"
 540 VALIGN="top"
 541 ><SPAN
 542 CLASS="PROPERTY"
 543 >hardware</SPAN
 544 ></TD
 545 ></TR
 546 ></TABLE
 547 ></DIV
 548 ></BODY
 549 ></HTML
 550 >