doc/html/cdl-guide/ref.active-if.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 >active_if</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_interface"
  26 HREF="ref.cdl-interface.html"><LINK
  27 REL="NEXT"
  28 TITLE="calculated"
  29 HREF="ref.calculated.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.cdl-interface.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.calculated.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.ACTIVE-IF"><SPAN
  86 CLASS="PROPERTY"
  87 >active_if</SPAN
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN3662"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Property <SPAN
  97 CLASS="PROPERTY"
  98 >active_if</SPAN
  99 >&nbsp;--&nbsp;Allow additional control over the active state of an
 100 option or other CDL entity.</DIV
 101 ><DIV
 102 CLASS="REFSYNOPSISDIV"
 103 ><A
 104 NAME="AEN3666"><H2
 105 >Synopsis</H2
 106 ><TABLE
 107 BORDER="5"
 108 BGCOLOR="#E0E0F0"
 109 WIDTH="70%"
 110 ><TR
 111 ><TD
 112 ><PRE
 113 CLASS="SYNOPSIS"
 114 >cdl_option &lt;name&gt; {
 115     active_if &lt;condition&gt;
 116     &#8230;
 117 }</PRE
 118 ></TD
 119 ></TR
 120 ></TABLE
 121 ></DIV
 122 ><DIV
 123 CLASS="REFSECT1"
 124 ><A
 125 NAME="AEN3668"
 126 ></A
 127 ><H2
 128 >Description</H2
 129 ><P
 130 >Configuration options or other entities may be either active or
 131 inactive. Typically this is controlled by the option's location in the
 132 overall hierarchy. Consider the option
 133 <TT
 134 CLASS="LITERAL"
 135 >CYGDBG_INFRA_DEBUG_PRECONDITIONS</TT
 136 >, which exists
 137 below the component <TT
 138 CLASS="LITERAL"
 139 >CYGDBG_USE_ASSERT</TT
 140 >. If the whole
 141 component is disabled then the options it contains are inactive: there
 142 is no point in enabling preconditions unless there is generic
 143 assertion support; any <SPAN
 144 CLASS="PROPERTY"
 145 >requires</SPAN
 146 > constraints associated with
 147 preconditions are irrelevant; any <SPAN
 148 CLASS="PROPERTY"
 149 >compile</SPAN
 150 > property or other
 151 build-related property is ignored.</P
 152 ><P
 153 >In some cases the hierarchy does not provide sufficient control over
 154 whether or not a particular option should be active. For example, the
 155 math library could have support for floating point exceptions which
 156 is only worthwhile if the hardware implements appropriate
 157 functionality, as specified by the architectural HAL. The relevant
 158 math library configuration options should remain below the
 159 <TT
 160 CLASS="LITERAL"
 161 >CYGPKG_LIBM</TT
 162 > package in the overall hierarchy, but
 163 should be inactive unless there is appropriate hardware support. In
 164 cases like this an <SPAN
 165 CLASS="PROPERTY"
 166 >active_if</SPAN
 167 > property is appropriate.</P
 168 ><P
 169 >Another common use of <SPAN
 170 CLASS="PROPERTY"
 171 >active_if</SPAN
 172 > properties is to avoid excessive
 173 nesting in the configuration hierarchy. If some option B is only
 174 relevant if option A is enabled, it is possible to turn A into a
 175 component that contains B. However adding another level to the
 176 hierarchy for a component which will contain just one entry may be
 177 considered excessive. In such cases it is possible for B to have an
 178 <SPAN
 179 CLASS="PROPERTY"
 180 >active_if</SPAN
 181 > dependency on A.</P
 182 ><P
 183 ><SPAN
 184 CLASS="PROPERTY"
 185 >active_if</SPAN
 186 > takes a goal expression as argument. For details of goal
 187 expression syntax see <A
 188 HREF="language.values.html#LANGUAGE.GOAL-EXPRESSION"
 189 >the Section called <I
 190 >Goal Expressions</I
 191 > in Chapter 3</A
 192 >. In
 193 most cases the goal expression will be very simple, often involving
 194 just one other option, but more complicated expressions can be used
 195 when appropriate. It is also possible to have multiple <SPAN
 196 CLASS="PROPERTY"
 197 >active_if</SPAN
 198 >
 199 conditions in a single option, in which case all of the conditions
 200 have to be satisfied if the option is to be active.</P
 201 ><P
 202 >The <SPAN
 203 CLASS="PROPERTY"
 204 >active_if</SPAN
 205 > and <SPAN
 206 CLASS="PROPERTY"
 207 >requires</SPAN
 208 > properties have certain similarities,
 209 but they serve a different purpose. Suppose there are two options A
 210 and B, and option B relies on functionality provided by A. This could
 211 be expressed as either <TT
 212 CLASS="LITERAL"
 213 >active_if&nbsp;A</TT
 214 > or as
 215 <TT
 216 CLASS="LITERAL"
 217 >requires&nbsp;A</TT
 218 >. The points to note are:</P
 219 ><P
 220 ></P
 221 ><UL
 222 ><LI
 223 ><P
 224 >If <TT
 225 CLASS="LITERAL"
 226 >active_if&nbsp;A</TT
 227 > is used and A is disabled or
 228 inactive, then graphical tools will generally prevent any attempt at
 229 modifying B. For example the text for B could be grayed out, and the
 230 associated checkbutton (if B is a boolean option) would be disabled.
 231 If the user needs the functionality provided by option B then it is
 232 necessary to go to option A first and manipulate it appropriately.</P
 233 ></LI
 234 ><LI
 235 ><P
 236 >If <TT
 237 CLASS="LITERAL"
 238 >requires&nbsp;A</TT
 239 > is used and A is disabled or
 240 inactive, graphical tools will still allow B to be manipulated and
 241 enabled. This would result in a new conflict which may get resolved
 242 automatically or which may need user intervention.</P
 243 ></LI
 244 ><LI
 245 ><P
 246 >If there are hardware dependencies then an <SPAN
 247 CLASS="PROPERTY"
 248 >active_if</SPAN
 249 > condition is
 250 usually the preferred approach. There is no point in allowing the user
 251 to manipulate a configuration option if the corresponding
 252 functionality cannot possibly work on the currently-selected hardware.
 253 Much the same argument applies to coarse-grained dependencies, for
 254 example if an option depends on the presence of a TCP/IP stack then an
 255 <TT
 256 CLASS="LITERAL"
 257 >active_if&nbsp;CYGPKG_NET</TT
 258 > condition is appropriate:
 259 it may be possible to satisfy the condition, but it requires the
 260 fairly drastic step of loading another package; further more, if the
 261 user wanted a TCP/IP stack in the configuration then it would probably
 262 have been loaded already. </P
 263 ></LI
 264 ><LI
 265 ><P
 266 >If option B exists to provide additional debugging information about
 267 the functionality provided by A then again an <SPAN
 268 CLASS="PROPERTY"
 269 >active_if</SPAN
 270 > constraint
 271 is appropriate. There is no point in letting users enable extra
 272 debugging facilities for a feature that is not actually present.</P
 273 ></LI
 274 ><LI
 275 ><P
 276 >The configuration system's inference engine will cope equally well
 277 with <SPAN
 278 CLASS="PROPERTY"
 279 >active_if</SPAN
 280 > and <SPAN
 281 CLASS="PROPERTY"
 282 >requires</SPAN
 283 > properties. Suppose there is a
 284 conflict because some third option depends on B. If B is
 285 <TT
 286 CLASS="LITERAL"
 287 >active_if&nbsp;A</TT
 288 > then the inference engine will
 289 attempt to make A active and enabled, and then to enable B if
 290 necessary. If B <TT
 291 CLASS="LITERAL"
 292 >requires&nbsp;A</TT
 293 > then the inference
 294 engine will attempt to enable B and resolve the resulting conflict by
 295 causing A to be both active and enabled. Although the inference occurs
 296 in a different order, in most cases the effect will be the same.</P
 297 ></LI
 298 ></UL
 299 ></DIV
 300 ><DIV
 301 CLASS="REFSECT1"
 302 ><A
 303 NAME="AEN3710"
 304 ></A
 305 ><H2
 306 >Example</H2
 307 ><TABLE
 308 BORDER="5"
 309 BGCOLOR="#E0E0F0"
 310 WIDTH="70%"
 311 ><TR
 312 ><TD
 313 ><PRE
 314 CLASS="PROGRAMLISTING"
 315 ># Do not provide extra semaphore debugging if there are no semaphores
 316 cdl_option CYGDBG_KERNEL_INSTRUMENT_BINSEM {
 317     active_if CYGPKG_KERNEL_SYNCH
 318     &#8230;
 319 }
 320
 321 # Avoid another level in the configuration hierarchy
 322 cdl_option CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INHERITANCE_SIMPLE_RELAY {
 323     active_if CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INHERITANCE_SIMPLE
 324     &#8230;
 325 }
 326
 327 # Functionality that is only relevant if another package is loaded
 328 cdl_option CYGSEM_START_UITRON_COMPATIBILITY {
 329     active_if CYGPKG_UITRON
 330     &#8230;
 331 }
 332
 333 # Check that the hardware or HAL provide the appropriate functionality
 334 cdl_option CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT {
 335     active_if CYGINT_HAL_DEBUG_GDB_STUBS_BREAK
 336     &#8230;
 337 }</PRE
 338 ></TD
 339 ></TR
 340 ></TABLE
 341 ></DIV
 342 ><DIV
 343 CLASS="REFSECT1"
 344 ><A
 345 NAME="AEN3713"
 346 ></A
 347 ><H2
 348 >See Also</H2
 349 ><P
 350 >Property <A
 351 HREF="ref.requires.html"
 352 ><SPAN
 353 CLASS="PROPERTY"
 354 >requires</SPAN
 355 ></A
 356 >.</P
 357 ></DIV
 358 ><DIV
 359 CLASS="NAVFOOTER"
 360 ><HR
 361 ALIGN="LEFT"
 362 WIDTH="100%"><TABLE
 363 SUMMARY="Footer navigation table"
 364 WIDTH="100%"
 365 BORDER="0"
 366 CELLPADDING="0"
 367 CELLSPACING="0"
 368 ><TR
 369 ><TD
 370 WIDTH="33%"
 371 ALIGN="left"
 372 VALIGN="top"
 373 ><A
 374 HREF="ref.cdl-interface.html"
 375 ACCESSKEY="P"
 376 >Prev</A
 377 ></TD
 378 ><TD
 379 WIDTH="34%"
 380 ALIGN="center"
 381 VALIGN="top"
 382 ><A
 383 HREF="cdl-guide.html"
 384 ACCESSKEY="H"
 385 >Home</A
 386 ></TD
 387 ><TD
 388 WIDTH="33%"
 389 ALIGN="right"
 390 VALIGN="top"
 391 ><A
 392 HREF="ref.calculated.html"
 393 ACCESSKEY="N"
 394 >Next</A
 395 ></TD
 396 ></TR
 397 ><TR
 398 ><TD
 399 WIDTH="33%"
 400 ALIGN="left"
 401 VALIGN="top"
 402 ><TT
 403 CLASS="LITERAL"
 404 >cdl_interface</TT
 405 ></TD
 406 ><TD
 407 WIDTH="34%"
 408 ALIGN="center"
 409 VALIGN="top"
 410 ><A
 411 HREF="reference.html"
 412 ACCESSKEY="U"
 413 >Up</A
 414 ></TD
 415 ><TD
 416 WIDTH="33%"
 417 ALIGN="right"
 418 VALIGN="top"
 419 ><SPAN
 420 CLASS="PROPERTY"
 421 >calculated</SPAN
 422 ></TD
 423 ></TR
 424 ></TABLE
 425 ></DIV
 426 ></BODY
 427 ></HTML
 428 >