doc/html/cdl-guide/ref.default-value.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 >default_value</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="compile"
  26 HREF="ref.compile.html"><LINK
  27 REL="NEXT"
  28 TITLE="define"
  29 HREF="ref.define.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.compile.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.define.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.DEFAULT-VALUE"><SPAN
  86 CLASS="PROPERTY"
  87 >default_value</SPAN
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN3887"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Property <SPAN
  97 CLASS="PROPERTY"
  98 >default_value</SPAN
  99 >&nbsp;--&nbsp;Provide a default value for this option using a CDL expression.</DIV
 100 ><DIV
 101 CLASS="REFSYNOPSISDIV"
 102 ><A
 103 NAME="AEN3891"><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     default_value &lt;expression&gt;
 115     &#8230;
 116 }</PRE
 117 ></TD
 118 ></TR
 119 ></TABLE
 120 ></DIV
 121 ><DIV
 122 CLASS="REFSECT1"
 123 ><A
 124 NAME="AEN3893"
 125 ></A
 126 ><H2
 127 >Description</H2
 128 ><P
 129 >The <SPAN
 130 CLASS="PROPERTY"
 131 >default_value</SPAN
 132 > property allows the initial value of a
 133 configuration option to depend on other configuration options. The
 134 arguments to the property should be a <SPAN
 135 CLASS="APPLICATION"
 136 >CDL</SPAN
 137 > expression, see
 138 <A
 139 HREF="language.values.html#LANGUAGE.EXPRESSION"
 140 >the Section called <I
 141 >Ordinary Expressions</I
 142 > in Chapter 3</A
 143 > for the syntactic details.
 144 In many cases a simple constant value will suffice, for example:</P
 145 ><TABLE
 146 BORDER="5"
 147 BGCOLOR="#E0E0F0"
 148 WIDTH="70%"
 149 ><TR
 150 ><TD
 151 ><PRE
 152 CLASS="PROGRAMLISTING"
 153 >cdl_component CYGPKG_KERNEL_EXCEPTIONS {
 154     &#8230;
 155     default_value 1
 156
 157     cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE {
 158         &#8230;
 159         default_value 0
 160     }
 161 }</PRE
 162 ></TD
 163 ></TR
 164 ></TABLE
 165 ><P
 166 >However it is also possible for an option's default value to depend on
 167 other options. For example the common HAL package provides some
 168 support functions that are needed by the <SPAN
 169 CLASS="APPLICATION"
 170 >eCos</SPAN
 171 > kernel, but are
 172 unlikely to be useful if the kernel is not being used. This
 173 relationship can be expressed using:</P
 174 ><TABLE
 175 BORDER="5"
 176 BGCOLOR="#E0E0F0"
 177 WIDTH="70%"
 178 ><TR
 179 ><TD
 180 ><PRE
 181 CLASS="PROGRAMLISTING"
 182 >cdl_option CYGFUN_HAL_COMMON_KERNEL_SUPPORT {
 183     ...
 184     default_value CYGPKG_KERNEL
 185 }</PRE
 186 ></TD
 187 ></TR
 188 ></TABLE
 189 ><P
 190 >If the kernel is loaded then this HAL option is automatically enabled,
 191 although the user can still disable it explicitly should this prove
 192 necessary. If the kernel is not loaded then the option is disabled,
 193 although it can still be enabled by the user if desired.
 194 <SPAN
 195 CLASS="PROPERTY"
 196 >default_value</SPAN
 197 > expressions can be more complicated than this if
 198 appropriate, and provide a very powerful facility for component
 199 writers who want their code to &#8220;just do the right thing&#8221;
 200 in a wide variety of configurations.</P
 201 ><P
 202 >The <SPAN
 203 CLASS="APPLICATION"
 204 >CDL</SPAN
 205 > configuration system evaluates the <SPAN
 206 CLASS="PROPERTY"
 207 >default_value</SPAN
 208 >
 209 expression when the current package is loaded and whenever there is a
 210 change to any other option referenced in the expression. The result
 211 depends on the option's flavor:</P
 212 ><P
 213 ></P
 214 ><DIV
 215 CLASS="VARIABLELIST"
 216 ><DL
 217 ><DT
 218 ><TT
 219 CLASS="LITERAL"
 220 >flavor none</TT
 221 ></DT
 222 ><DD
 223 ><P
 224 >Options with this flavor have no value, so the <SPAN
 225 CLASS="PROPERTY"
 226 >default_value</SPAN
 227 >
 228 property is not applicable.</P
 229 ></DD
 230 ><DT
 231 ><TT
 232 CLASS="LITERAL"
 233 >flavor bool</TT
 234 ></DT
 235 ><DD
 236 ><P
 237 >If the expression evaluates to a non-zero result the option is
 238 enabled by default, otherwise it is disabled.</P
 239 ></DD
 240 ><DT
 241 ><TT
 242 CLASS="LITERAL"
 243 >flavor booldata</TT
 244 ></DT
 245 ><DD
 246 ><P
 247 >If the result of evaluating the expression is zero then the option is
 248 disabled, otherwise the option is enabled and its value is the result.</P
 249 ></DD
 250 ><DT
 251 ><TT
 252 CLASS="LITERAL"
 253 >flavor data</TT
 254 ></DT
 255 ><DD
 256 ><P
 257 >The default value of the option is the result of evaluating the
 258 expression.</P
 259 ></DD
 260 ></DL
 261 ></DIV
 262 ><P
 263 >A <TT
 264 CLASS="LITERAL"
 265 >cdl_option</TT
 266 > or other entity can have at most one <SPAN
 267 CLASS="PROPERTY"
 268 >default_value</SPAN
 269 >
 270 property, and it is illegal to have both a <SPAN
 271 CLASS="PROPERTY"
 272 >calculated</SPAN
 273 > and a
 274 <SPAN
 275 CLASS="PROPERTY"
 276 >default_value</SPAN
 277 > property in one body. If an option does not have
 278 either a <SPAN
 279 CLASS="PROPERTY"
 280 >default_value</SPAN
 281 > or a <SPAN
 282 CLASS="PROPERTY"
 283 >calculated</SPAN
 284 > property and it does not
 285 have the flavor <TT
 286 CLASS="LITERAL"
 287 >none</TT
 288 > then the configuration tools
 289 will assume a default value expression of <TT
 290 CLASS="LITERAL"
 291 >0</TT
 292 >.</P
 293 ><P
 294 >On occasion it is useful to have a configuration option
 295 <TT
 296 CLASS="LITERAL"
 297 >A</TT
 298 > which has both a <SPAN
 299 CLASS="PROPERTY"
 300 >requires</SPAN
 301 > constraint on some
 302 other option <TT
 303 CLASS="LITERAL"
 304 >B</TT
 305 > and a <SPAN
 306 CLASS="PROPERTY"
 307 >default_value</SPAN
 308 > expression of
 309 <TT
 310 CLASS="LITERAL"
 311 >B</TT
 312 >. If option <TT
 313 CLASS="LITERAL"
 314 >B</TT
 315 > is not enabled
 316 then <TT
 317 CLASS="LITERAL"
 318 >A</TT
 319 > will also be disabled by default and no
 320 conflict arises. If <TT
 321 CLASS="LITERAL"
 322 >B</TT
 323 > is enabled then
 324 <TT
 325 CLASS="LITERAL"
 326 >A</TT
 327 > also becomes enabled and again no conflict
 328 arises. If a user attempts to enable <TT
 329 CLASS="LITERAL"
 330 >B</TT
 331 > but not
 332 <TT
 333 CLASS="LITERAL"
 334 >A</TT
 335 > then there will be a conflict. Users should be
 336 able to deduce that the two options are closely interlinked and should
 337 not be manipulated independently except in very unusual circumstances.</P
 338 ><DIV
 339 CLASS="TIP"
 340 ><BLOCKQUOTE
 341 CLASS="TIP"
 342 ><P
 343 ><B
 344 >Tip: </B
 345 >If the first entry in a <SPAN
 346 CLASS="PROPERTY"
 347 >default_value</SPAN
 348 > expression is a negative
 349 number, for example <TT
 350 CLASS="LITERAL"
 351 >default_value&nbsp;-1</TT
 352 > then this
 353 can be misinterpreted as an option instead of as part of the
 354 expression. Currently the <SPAN
 355 CLASS="PROPERTY"
 356 >default_value</SPAN
 357 > property does not take any
 358 options, but this may change in future. Option processing halts at the
 359 sequence <TT
 360 CLASS="LITERAL"
 361 >--</TT
 362 >, so the desired value can be expressed
 363 safely using
 364 <TT
 365 CLASS="LITERAL"
 366 >default_value&nbsp;--&nbsp;-1</TT
 367 ></P
 368 ></BLOCKQUOTE
 369 ></DIV
 370 ><DIV
 371 CLASS="NOTE"
 372 ><BLOCKQUOTE
 373 CLASS="NOTE"
 374 ><P
 375 ><B
 376 >Note: </B
 377 >In many cases it would be useful to calculate default values using
 378 some global preferences, for example:</P
 379 ><TABLE
 380 BORDER="5"
 381 BGCOLOR="#E0E0F0"
 382 WIDTH="70%"
 383 ><TR
 384 ><TD
 385 ><PRE
 386 CLASS="PROGRAMLISTING"
 387 >cdl_option CYGIMP_LIBC_STRING_PREFER_SMALL_TO_FAST {
 388     &#8230;
 389     default_value CYGGLO_CODESIZE &#62; CYGGLO_SPEED
 390 }</PRE
 391 ></TD
 392 ></TR
 393 ></TABLE
 394 ><P
 395 >Such global preference options do not yet exist, but are likely to be
 396 added in a future version.</P
 397 ></BLOCKQUOTE
 398 ></DIV
 399 ><DIV
 400 CLASS="NOTE"
 401 ><BLOCKQUOTE
 402 CLASS="NOTE"
 403 ><P
 404 ><B
 405 >Note: </B
 406 >For options with the booldata flavor the current syntax does not allow
 407 the default values of the enabled flag and the value to be controlled
 408 separately. Functionality to permit this may be added in a future
 409 release.</P
 410 ></BLOCKQUOTE
 411 ></DIV
 412 ></DIV
 413 ><DIV
 414 CLASS="REFSECT1"
 415 ><A
 416 NAME="AEN3964"
 417 ></A
 418 ><H2
 419 >Example</H2
 420 ><TABLE
 421 BORDER="5"
 422 BGCOLOR="#E0E0F0"
 423 WIDTH="70%"
 424 ><TR
 425 ><TD
 426 ><PRE
 427 CLASS="PROGRAMLISTING"
 428 >cdl_option CYGDBG_HAL_DEBUG_GDB_THREAD_SUPPORT {
 429     display       "Include GDB multi-threading debug support"
 430     requires      CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
 431     default_value CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
 432     description   "
 433         This option enables some extra HAL code which is needed
 434         to support multi-threaded source level debugging."
 435 }</PRE
 436 ></TD
 437 ></TR
 438 ></TABLE
 439 ></DIV
 440 ><DIV
 441 CLASS="REFSECT1"
 442 ><A
 443 NAME="AEN3967"
 444 ></A
 445 ><H2
 446 >See Also</H2
 447 ><P
 448 >Properties <A
 449 HREF="ref.calculated.html"
 450 ><SPAN
 451 CLASS="PROPERTY"
 452 >calculated</SPAN
 453 ></A
 454 >,
 455 <A
 456 HREF="ref.flavor.html"
 457 ><SPAN
 458 CLASS="PROPERTY"
 459 >flavor</SPAN
 460 ></A
 461 > and
 462 <A
 463 HREF="ref.legal-values.html"
 464 ><SPAN
 465 CLASS="PROPERTY"
 466 >legal_values</SPAN
 467 ></A
 468 >.</P
 469 ></DIV
 470 ><DIV
 471 CLASS="NAVFOOTER"
 472 ><HR
 473 ALIGN="LEFT"
 474 WIDTH="100%"><TABLE
 475 SUMMARY="Footer navigation table"
 476 WIDTH="100%"
 477 BORDER="0"
 478 CELLPADDING="0"
 479 CELLSPACING="0"
 480 ><TR
 481 ><TD
 482 WIDTH="33%"
 483 ALIGN="left"
 484 VALIGN="top"
 485 ><A
 486 HREF="ref.compile.html"
 487 ACCESSKEY="P"
 488 >Prev</A
 489 ></TD
 490 ><TD
 491 WIDTH="34%"
 492 ALIGN="center"
 493 VALIGN="top"
 494 ><A
 495 HREF="cdl-guide.html"
 496 ACCESSKEY="H"
 497 >Home</A
 498 ></TD
 499 ><TD
 500 WIDTH="33%"
 501 ALIGN="right"
 502 VALIGN="top"
 503 ><A
 504 HREF="ref.define.html"
 505 ACCESSKEY="N"
 506 >Next</A
 507 ></TD
 508 ></TR
 509 ><TR
 510 ><TD
 511 WIDTH="33%"
 512 ALIGN="left"
 513 VALIGN="top"
 514 ><SPAN
 515 CLASS="PROPERTY"
 516 >compile</SPAN
 517 ></TD
 518 ><TD
 519 WIDTH="34%"
 520 ALIGN="center"
 521 VALIGN="top"
 522 ><A
 523 HREF="reference.html"
 524 ACCESSKEY="U"
 525 >Up</A
 526 ></TD
 527 ><TD
 528 WIDTH="33%"
 529 ALIGN="right"
 530 VALIGN="top"
 531 ><SPAN
 532 CLASS="PROPERTY"
 533 >define</SPAN
 534 ></TD
 535 ></TR
 536 ></TABLE
 537 ></DIV
 538 ></BODY
 539 ></HTML
 540 >