doc/html/cdl-guide/ref.if-define.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 >if_define</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="hardware"
  26 HREF="ref.hardware.html"><LINK
  27 REL="NEXT"
  28 TITLE="implements"
  29 HREF="ref.implements.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.hardware.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.implements.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.IF-DEFINE"><SPAN
  86 CLASS="PROPERTY"
  87 >if_define</SPAN
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN4442"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Property <SPAN
  97 CLASS="PROPERTY"
  98 >if_define</SPAN
  99 >&nbsp;--&nbsp;Output a common preprocessor construct to a configuration
 100 header file.</DIV
 101 ><DIV
 102 CLASS="REFSYNOPSISDIV"
 103 ><A
 104 NAME="AEN4446"><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     if_define [-file=&lt;filename&gt;] &lt;symbol1&gt; &lt;symbol2&gt;
 116     &#8230;
 117 }</PRE
 118 ></TD
 119 ></TR
 120 ></TABLE
 121 ></DIV
 122 ><DIV
 123 CLASS="REFSECT1"
 124 ><A
 125 NAME="AEN4448"
 126 ></A
 127 ><H2
 128 >Description</H2
 129 ><P
 130 >The purpose of the <SPAN
 131 CLASS="PROPERTY"
 132 >if_define</SPAN
 133 > property is best explained by an
 134 example. Suppose you want finer-grained control over assertions, say
 135 on a per-package or even a per-file basis rather than globally. The
 136 assertion macros can be defined by an exported header file in an
 137 infrastructure package, using code like the following:</P
 138 ><TABLE
 139 BORDER="5"
 140 BGCOLOR="#E0E0F0"
 141 WIDTH="70%"
 142 ><TR
 143 ><TD
 144 ><PRE
 145 CLASS="PROGRAMLISTING"
 146 >#ifdef CYGDBG_USE_ASSERTS
 147 # define CYG_ASSERT( _bool_, _msg_ )    \
 148         CYG_MACRO_START                 \
 149         if ( ! ( _bool_ ) )             \
 150             CYG_ASSERT_DOCALL( _msg_ ); \
 151         CYG_MACRO_END
 152 #else
 153 # define CYG_ASSERT( _bool_, _msg_ ) CYG_EMPTY_STATEMENT
 154 #endif</PRE
 155 ></TD
 156 ></TR
 157 ></TABLE
 158 ><P
 159 >Assuming this header file is <TT
 160 CLASS="LITERAL"
 161 >#include'd</TT
 162 > directly or
 163 indirectly by any code which may need to be built with assertions
 164 enabled, the challenge is now to control whether or not
 165 <TT
 166 CLASS="VARNAME"
 167 >CYGDBG_USE_ASSERTS</TT
 168 > is defined for any given source
 169 file. This is the purpose of the <SPAN
 170 CLASS="PROPERTY"
 171 >if_define</SPAN
 172 > property:</P
 173 ><TABLE
 174 BORDER="5"
 175 BGCOLOR="#E0E0F0"
 176 WIDTH="70%"
 177 ><TR
 178 ><TD
 179 ><PRE
 180 CLASS="PROGRAMLISTING"
 181 >cdl_option CYGDBG_KERNEL_USE_ASSERTS {
 182     &#8230;
 183     if_define CYGSRC_KERNEL CYGDBG_USE_ASSERTS
 184     requires  CYGDBG_INFRA_ASSERTION_SUPPORT
 185 }</PRE
 186 ></TD
 187 ></TR
 188 ></TABLE
 189 ><P
 190 >If this option is active and enabled then the kernel's configuration
 191 header file would end up containing the following:</P
 192 ><TABLE
 193 BORDER="5"
 194 BGCOLOR="#E0E0F0"
 195 WIDTH="70%"
 196 ><TR
 197 ><TD
 198 ><PRE
 199 CLASS="PROGRAMLISTING"
 200 >#ifdef CYGSRC_KERNEL
 201 # define CYGDBG_USE_ASSERTS 1
 202 #endif</PRE
 203 ></TD
 204 ></TR
 205 ></TABLE
 206 ><P
 207 >Kernel source code can now begin with the following construct:</P
 208 ><TABLE
 209 BORDER="5"
 210 BGCOLOR="#E0E0F0"
 211 WIDTH="70%"
 212 ><TR
 213 ><TD
 214 ><PRE
 215 CLASS="PROGRAMLISTING"
 216 >#define CYGSRC_KERNEL 1
 217 #include &lt;pkgconf/kernel.h&gt;
 218 #include &lt;cyg/infra/cyg_ass.h&gt;</PRE
 219 ></TD
 220 ></TR
 221 ></TABLE
 222 ><P
 223 >The configuration option only affects kernel source code, assuming
 224 nothing else <TT
 225 CLASS="LITERAL"
 226 >#define's</TT
 227 > the symbol
 228 <TT
 229 CLASS="VARNAME"
 230 >CYGSRC_KERNEL</TT
 231 >. If the per-package assertion option
 232 is disabled then <TT
 233 CLASS="VARNAME"
 234 >CYGDBG_USE_ASSERTS</TT
 235 > will not get
 236 defined. If the option is enabled then
 237 <TT
 238 CLASS="VARNAME"
 239 >CYGDBG_USE_ASSERTS</TT
 240 > will get defined and assertions
 241 will be enabled for the kernel sources. It is possible to use the same
 242 mechanism for other facilities such as tracing, and to apply it at a
 243 finer grain such as individual source files by having multiple options
 244 with <SPAN
 245 CLASS="PROPERTY"
 246 >if_define</SPAN
 247 > properties and multiple symbols such as
 248 <TT
 249 CLASS="VARNAME"
 250 >CYGSRC_KERNEL_SCHED_BITMAP_CXX</TT
 251 >.</P
 252 ><P
 253 >The <SPAN
 254 CLASS="PROPERTY"
 255 >if_define</SPAN
 256 > property takes two arguments, both of which must be
 257 valid C preprocessor symbols. If the current option is active and
 258 enabled then three lines will be output to the configuration header
 259 file:</P
 260 ><TABLE
 261 BORDER="5"
 262 BGCOLOR="#E0E0F0"
 263 WIDTH="70%"
 264 ><TR
 265 ><TD
 266 ><PRE
 267 CLASS="PROGRAMLISTING"
 268 >#ifdef &lt;symbol1&gt;
 269 # define &lt;symbol2&gt;
 270 #endif</PRE
 271 ></TD
 272 ></TR
 273 ></TABLE
 274 ><P
 275 >If the option is inactive or disabled then these lines will not be
 276 output. By default the current package's configuration header file
 277 will be used, but it is possible to specify an alternative destination
 278 using a <TT
 279 CLASS="LITERAL"
 280 >-file</TT
 281 > option. At present the only
 282 legitimate alternative destination is <TT
 283 CLASS="LITERAL"
 284 >system.h</TT
 285 >, the
 286 global configuration header. <SPAN
 287 CLASS="PROPERTY"
 288 >if_define</SPAN
 289 > processing happens in
 290 addition to, not instead of, the normal <TT
 291 CLASS="LITERAL"
 292 >#define</TT
 293 >
 294 processing or the handling of other header-file related properties.</P
 295 ><DIV
 296 CLASS="NOTE"
 297 ><BLOCKQUOTE
 298 CLASS="NOTE"
 299 ><P
 300 ><B
 301 >Note: </B
 302 >The infrastructure in the current <SPAN
 303 CLASS="APPLICATION"
 304 >eCos</SPAN
 305 > release does not yet work
 306 this way. In future it may do so, and the intention is that suitable
 307 configuration options get generated semi-automatically by the
 308 configuration system rather than having to be defined explicitly.</P
 309 ></BLOCKQUOTE
 310 ></DIV
 311 ><DIV
 312 CLASS="TIP"
 313 ><BLOCKQUOTE
 314 CLASS="TIP"
 315 ><P
 316 ><B
 317 >Tip: </B
 318 >As an alternative to changing the configuration, updating the build
 319 tree, and so on, it is possible to enable assertions by editing a
 320 source file directly, for example:</P
 321 ><TABLE
 322 BORDER="5"
 323 BGCOLOR="#E0E0F0"
 324 WIDTH="70%"
 325 ><TR
 326 ><TD
 327 ><PRE
 328 CLASS="PROGRAMLISTING"
 329 >#define CYGSRC_KERNEL 1
 330 #define CYGDBG_USE_ASSERTS 1
 331 #include &lt;pkgconf/kernel.h&gt;
 332 #include &lt;cyg/infra/cyg_ass.h&gt;</PRE
 333 ></TD
 334 ></TR
 335 ></TABLE
 336 ><P
 337 >The assertion header file does not care whether
 338 <TT
 339 CLASS="VARNAME"
 340 >CYGDBG_USE_ASSERTS</TT
 341 > is <TT
 342 CLASS="LITERAL"
 343 >#define'd</TT
 344 >
 345 via a configuration option or by explicit code. This technique can be
 346 useful to component writers when debugging their source code, although
 347 care has to be taken to remove any such <TT
 348 CLASS="LITERAL"
 349 >#define's</TT
 350 >
 351 later on.</P
 352 ></BLOCKQUOTE
 353 ></DIV
 354 ></DIV
 355 ><DIV
 356 CLASS="REFSECT1"
 357 ><A
 358 NAME="AEN4487"
 359 ></A
 360 ><H2
 361 >Example</H2
 362 ><TABLE
 363 BORDER="5"
 364 BGCOLOR="#E0E0F0"
 365 WIDTH="70%"
 366 ><TR
 367 ><TD
 368 ><PRE
 369 CLASS="PROGRAMLISTING"
 370 >cdl_option CYGDBG_KERNEL_USE_ASSERTS {
 371     display "Assertions in the kernel package"
 372     &#8230;
 373     if_define CYGSRC_KERNEL CYGDBG_USE_ASSERTS
 374     requires  CYGDBG_INFRA_ASSERTION_SUPPORT
 375 }</PRE
 376 ></TD
 377 ></TR
 378 ></TABLE
 379 ></DIV
 380 ><DIV
 381 CLASS="REFSECT1"
 382 ><A
 383 NAME="AEN4490"
 384 ></A
 385 ><H2
 386 >See Also</H2
 387 ><P
 388 >Properties <A
 389 HREF="ref.define.html"
 390 ><SPAN
 391 CLASS="PROPERTY"
 392 >define</SPAN
 393 ></A
 394 >,
 395 <A
 396 HREF="ref.define-format.html"
 397 ><SPAN
 398 CLASS="PROPERTY"
 399 >define_format</SPAN
 400 ></A
 401 >,
 402 <A
 403 HREF="ref.define-header.html"
 404 ><SPAN
 405 CLASS="PROPERTY"
 406 >define_header</SPAN
 407 ></A
 408 >,
 409 <A
 410 HREF="ref.define-proc.html"
 411 ><SPAN
 412 CLASS="PROPERTY"
 413 >define_proc</SPAN
 414 ></A
 415 > and
 416 <A
 417 HREF="ref.no-define.html"
 418 ><SPAN
 419 CLASS="PROPERTY"
 420 >no_define</SPAN
 421 ></A
 422 >.</P
 423 ></DIV
 424 ><DIV
 425 CLASS="NAVFOOTER"
 426 ><HR
 427 ALIGN="LEFT"
 428 WIDTH="100%"><TABLE
 429 SUMMARY="Footer navigation table"
 430 WIDTH="100%"
 431 BORDER="0"
 432 CELLPADDING="0"
 433 CELLSPACING="0"
 434 ><TR
 435 ><TD
 436 WIDTH="33%"
 437 ALIGN="left"
 438 VALIGN="top"
 439 ><A
 440 HREF="ref.hardware.html"
 441 ACCESSKEY="P"
 442 >Prev</A
 443 ></TD
 444 ><TD
 445 WIDTH="34%"
 446 ALIGN="center"
 447 VALIGN="top"
 448 ><A
 449 HREF="cdl-guide.html"
 450 ACCESSKEY="H"
 451 >Home</A
 452 ></TD
 453 ><TD
 454 WIDTH="33%"
 455 ALIGN="right"
 456 VALIGN="top"
 457 ><A
 458 HREF="ref.implements.html"
 459 ACCESSKEY="N"
 460 >Next</A
 461 ></TD
 462 ></TR
 463 ><TR
 464 ><TD
 465 WIDTH="33%"
 466 ALIGN="left"
 467 VALIGN="top"
 468 ><SPAN
 469 CLASS="PROPERTY"
 470 >hardware</SPAN
 471 ></TD
 472 ><TD
 473 WIDTH="34%"
 474 ALIGN="center"
 475 VALIGN="top"
 476 ><A
 477 HREF="reference.html"
 478 ACCESSKEY="U"
 479 >Up</A
 480 ></TD
 481 ><TD
 482 WIDTH="33%"
 483 ALIGN="right"
 484 VALIGN="top"
 485 ><SPAN
 486 CLASS="PROPERTY"
 487 >implements</SPAN
 488 ></TD
 489 ></TR
 490 ></TABLE
 491 ></DIV
 492 ></BODY
 493 ></HTML
 494 >