doc/html/cdl-guide/ref.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 >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="default_value"
  26 HREF="ref.default-value.html"><LINK
  27 REL="NEXT"
  28 TITLE="define_format"
  29 HREF="ref.define-format.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.default-value.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-format.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.DEFINE"><SPAN
  86 CLASS="PROPERTY"
  87 >define</SPAN
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN3980"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Property <SPAN
  97 CLASS="PROPERTY"
  98 >define</SPAN
  99 >&nbsp;--&nbsp;Specify additional <TT
 100 CLASS="LITERAL"
 101 >#define</TT
 102 > symbols that
 103 should go into the owning package's configuration header file.</DIV
 104 ><DIV
 105 CLASS="REFSYNOPSISDIV"
 106 ><A
 107 NAME="AEN3985"><H2
 108 >Synopsis</H2
 109 ><TABLE
 110 BORDER="5"
 111 BGCOLOR="#E0E0F0"
 112 WIDTH="70%"
 113 ><TR
 114 ><TD
 115 ><PRE
 116 CLASS="SYNOPSIS"
 117 >cdl_option &lt;name&gt; {
 118     define [-file=&lt;filename&gt;] [-format=&lt;format&gt;] &lt;symbol&gt;
 119     &#8230;
 120 }</PRE
 121 ></TD
 122 ></TR
 123 ></TABLE
 124 ></DIV
 125 ><DIV
 126 CLASS="REFSECT1"
 127 ><A
 128 NAME="AEN3987"
 129 ></A
 130 ><H2
 131 >Description</H2
 132 ><P
 133 >Normally the configuration system generates a single
 134 <TT
 135 CLASS="LITERAL"
 136 >#define</TT
 137 > for each option that is active and enabled,
 138 with the defined symbol being the name of the option. These
 139 <TT
 140 CLASS="LITERAL"
 141 >#define's</TT
 142 > go to the package's own configuration
 143 header file, for example <TT
 144 CLASS="FILENAME"
 145 >pkgconf/kernel.h</TT
 146 >
 147 for kernel configuration options. For the majority of options this is
 148 sufficient. Sometimes it is useful to have more control over which
 149 <TT
 150 CLASS="LITERAL"
 151 >#define's</TT
 152 > get generated.</P
 153 ><P
 154 >The <SPAN
 155 CLASS="PROPERTY"
 156 >define</SPAN
 157 > property can be used to generate an addition
 158 <TT
 159 CLASS="LITERAL"
 160 >#define</TT
 161 > if the option is both active and enabled,
 162 for example:</P
 163 ><TABLE
 164 BORDER="5"
 165 BGCOLOR="#E0E0F0"
 166 WIDTH="70%"
 167 ><TR
 168 ><TD
 169 ><PRE
 170 CLASS="PROGRAMLISTING"
 171 >cdl_option CYGNUM_LIBC_STDIO_FOPEN_MAX {
 172     &#8230;
 173     define FOPEN_MAX
 174 }</PRE
 175 ></TD
 176 ></TR
 177 ></TABLE
 178 ><P
 179 >If this option is given the value 40 then the following
 180 <TT
 181 CLASS="LITERAL"
 182 >#define's</TT
 183 > will be generated in the configuration
 184 header <TT
 185 CLASS="FILENAME"
 186 >pkgconf/libc.h</TT
 187 >:</P
 188 ><TABLE
 189 BORDER="5"
 190 BGCOLOR="#E0E0F0"
 191 WIDTH="70%"
 192 ><TR
 193 ><TD
 194 ><PRE
 195 CLASS="SCREEN"
 196 >#define CYGNUM_LIBC_STDIO_FOPEN_MAX 40
 197 #define FOPEN_MAX 40</PRE
 198 ></TD
 199 ></TR
 200 ></TABLE
 201 ><P
 202 >The default <TT
 203 CLASS="LITERAL"
 204 >#define</TT
 205 > can be suppressed if desired
 206 using the <SPAN
 207 CLASS="PROPERTY"
 208 >no_define</SPAN
 209 > property. This is useful if the symbol should
 210 only be defined in
 211 <TT
 212 CLASS="FILENAME"
 213 >pkgconf/system.h</TT
 214 > and not in
 215 the package's own configuration header file. The value that will be
 216 used for this <TT
 217 CLASS="LITERAL"
 218 >#define</TT
 219 > is the same as for the
 220 default one, and depends on the option's flavor as follows:</P
 221 ><P
 222 ></P
 223 ><DIV
 224 CLASS="VARIABLELIST"
 225 ><DL
 226 ><DT
 227 ><TT
 228 CLASS="LITERAL"
 229 >flavor none</TT
 230 ></DT
 231 ><DD
 232 ><P
 233 >Options with this flavor are always enabled and have no value, so the
 234 constant <TT
 235 CLASS="LITERAL"
 236 >1</TT
 237 > will be used.</P
 238 ></DD
 239 ><DT
 240 ><TT
 241 CLASS="LITERAL"
 242 >flavor bool</TT
 243 ></DT
 244 ><DD
 245 ><P
 246 >If the option is disabled then no <TT
 247 CLASS="LITERAL"
 248 >#define</TT
 249 > will be
 250 generated. Otherwise the constant <TT
 251 CLASS="LITERAL"
 252 >1</TT
 253 > will be used.</P
 254 ></DD
 255 ><DT
 256 ><TT
 257 CLASS="LITERAL"
 258 >flavor booldata</TT
 259 ></DT
 260 ><DD
 261 ><P
 262 >If the option is disabled then no <TT
 263 CLASS="LITERAL"
 264 >#define</TT
 265 > will be
 266 generated. Otherwise the option's current value will be used.</P
 267 ></DD
 268 ><DT
 269 ><TT
 270 CLASS="LITERAL"
 271 >flavor data</TT
 272 ></DT
 273 ><DD
 274 ><P
 275 >The option's current value will be used.</P
 276 ></DD
 277 ></DL
 278 ></DIV
 279 ><P
 280 >For active options with the <TT
 281 CLASS="LITERAL"
 282 >data</TT
 283 > flavor, and for
 284 active and enabled options with the <TT
 285 CLASS="LITERAL"
 286 >booldata</TT
 287 >
 288 flavor, either one or two <TT
 289 CLASS="LITERAL"
 290 >#define's</TT
 291 > will be
 292 generated. These take the following forms:</P
 293 ><TABLE
 294 BORDER="5"
 295 BGCOLOR="#E0E0F0"
 296 WIDTH="70%"
 297 ><TR
 298 ><TD
 299 ><PRE
 300 CLASS="PROGRAMLISTING"
 301 >#define &lt;symbol&gt; &lt;value&gt;
 302 #define &lt;symbol&gt;_&lt;value&gt;</PRE
 303 ></TD
 304 ></TR
 305 ></TABLE
 306 ><P
 307 >For the first <TT
 308 CLASS="LITERAL"
 309 >#define</TT
 310 > it is possible to control the
 311 format used for the value using a
 312 <TT
 313 CLASS="LITERAL"
 314 >-format=&lt;format&gt;</TT
 315 > option. For example, the
 316 following can be used to output some configuration data as a C string:</P
 317 ><TABLE
 318 BORDER="5"
 319 BGCOLOR="#E0E0F0"
 320 WIDTH="70%"
 321 ><TR
 322 ><TD
 323 ><PRE
 324 CLASS="PROGRAMLISTING"
 325 >cdl_option &lt;name&gt; {
 326     &#8230;
 327     define -format="\\\"%s\\\"" &lt;symbol&gt;
 328 }</PRE
 329 ></TD
 330 ></TR
 331 ></TABLE
 332 ><P
 333 >The implementation of this facility involves concatenating the
 334 Tcl command <TT
 335 CLASS="LITERAL"
 336 >format</TT
 337 >, the format string, and the
 338 string representation of the option's value, and evaluating this in a
 339 Tcl interpreter. Therefore the format string will be processed twice
 340 by a Tcl parser, and appropriate care has to be taken with quoting.</P
 341 ><P
 342 >The second <TT
 343 CLASS="LITERAL"
 344 >#define</TT
 345 > will be generated only if is a
 346 valid C preprocessor macro symbol. By default the symbols generated by
 347 <SPAN
 348 CLASS="PROPERTY"
 349 >define</SPAN
 350 > properties will end up in the package's own configuration
 351 header file. The <TT
 352 CLASS="LITERAL"
 353 >-file</TT
 354 > option can be used to
 355 specify an alternative destination. At the time of writing the only
 356 valid alternative definition is <TT
 357 CLASS="LITERAL"
 358 >-file=system.h</TT
 359 >,
 360 which will send the output to the global configuration header file
 361 <TT
 362 CLASS="FILENAME"
 363 >pkgconf/system.h</TT
 364 >.</P
 365 ><DIV
 366 CLASS="CAUTION"
 367 ><P
 368 ></P
 369 ><TABLE
 370 CLASS="CAUTION"
 371 BORDER="1"
 372 WIDTH="100%"
 373 ><TR
 374 ><TD
 375 ALIGN="CENTER"
 376 ><B
 377 >Caution</B
 378 ></TD
 379 ></TR
 380 ><TR
 381 ><TD
 382 ALIGN="LEFT"
 383 ><P
 384 >Care has to be taken with the <TT
 385 CLASS="LITERAL"
 386 >-format</TT
 387 > option.
 388 Because the Tcl interpreter's <TT
 389 CLASS="LITERAL"
 390 >format</TT
 391 > command is
 392 used, this property is subject to any problems with the implementation
 393 of this in the Tcl library. Generally there should be no problems with
 394 string data or with integers up to 32 bits, but there may well be
 395 problems if 64-bit data is involved. This issue may be addressed in a
 396 future release.</P
 397 ></TD
 398 ></TR
 399 ></TABLE
 400 ></DIV
 401 ></DIV
 402 ><DIV
 403 CLASS="REFSECT1"
 404 ><A
 405 NAME="AEN4053"
 406 ></A
 407 ><H2
 408 >Example</H2
 409 ><TABLE
 410 BORDER="5"
 411 BGCOLOR="#E0E0F0"
 412 WIDTH="70%"
 413 ><TR
 414 ><TD
 415 ><PRE
 416 CLASS="PROGRAMLISTING"
 417 >cdl_component CYG_HAL_STARTUP {
 418     display       "Startup type"
 419     flavor        data
 420     legal_values  {"RAM" "ROM" }
 421     default_value {"RAM"}
 422     no_define
 423     define -file=system.h CYG_HAL_STARTUP
 424     &#8230;
 425 }</PRE
 426 ></TD
 427 ></TR
 428 ></TABLE
 429 ></DIV
 430 ><DIV
 431 CLASS="REFSECT1"
 432 ><A
 433 NAME="AEN4056"
 434 ></A
 435 ><H2
 436 >See Also</H2
 437 ><P
 438 >Properties <A
 439 HREF="ref.define-format.html"
 440 ><SPAN
 441 CLASS="PROPERTY"
 442 >define_format</SPAN
 443 ></A
 444 >,
 445 <A
 446 HREF="ref.define-header.html"
 447 ><SPAN
 448 CLASS="PROPERTY"
 449 >define_header</SPAN
 450 ></A
 451 >,
 452 <A
 453 HREF="ref.define-proc.html"
 454 ><SPAN
 455 CLASS="PROPERTY"
 456 >define_proc</SPAN
 457 ></A
 458 >,
 459 <A
 460 HREF="ref.if-define.html"
 461 ><SPAN
 462 CLASS="PROPERTY"
 463 >if_define</SPAN
 464 ></A
 465 > and
 466 <A
 467 HREF="ref.no-define.html"
 468 ><SPAN
 469 CLASS="PROPERTY"
 470 >no_define</SPAN
 471 ></A
 472 >.</P
 473 ></DIV
 474 ><DIV
 475 CLASS="NAVFOOTER"
 476 ><HR
 477 ALIGN="LEFT"
 478 WIDTH="100%"><TABLE
 479 SUMMARY="Footer navigation table"
 480 WIDTH="100%"
 481 BORDER="0"
 482 CELLPADDING="0"
 483 CELLSPACING="0"
 484 ><TR
 485 ><TD
 486 WIDTH="33%"
 487 ALIGN="left"
 488 VALIGN="top"
 489 ><A
 490 HREF="ref.default-value.html"
 491 ACCESSKEY="P"
 492 >Prev</A
 493 ></TD
 494 ><TD
 495 WIDTH="34%"
 496 ALIGN="center"
 497 VALIGN="top"
 498 ><A
 499 HREF="cdl-guide.html"
 500 ACCESSKEY="H"
 501 >Home</A
 502 ></TD
 503 ><TD
 504 WIDTH="33%"
 505 ALIGN="right"
 506 VALIGN="top"
 507 ><A
 508 HREF="ref.define-format.html"
 509 ACCESSKEY="N"
 510 >Next</A
 511 ></TD
 512 ></TR
 513 ><TR
 514 ><TD
 515 WIDTH="33%"
 516 ALIGN="left"
 517 VALIGN="top"
 518 ><SPAN
 519 CLASS="PROPERTY"
 520 >default_value</SPAN
 521 ></TD
 522 ><TD
 523 WIDTH="34%"
 524 ALIGN="center"
 525 VALIGN="top"
 526 ><A
 527 HREF="reference.html"
 528 ACCESSKEY="U"
 529 >Up</A
 530 ></TD
 531 ><TD
 532 WIDTH="33%"
 533 ALIGN="right"
 534 VALIGN="top"
 535 ><SPAN
 536 CLASS="PROPERTY"
 537 >define_format</SPAN
 538 ></TD
 539 ></TR
 540 ></TABLE
 541 ></DIV
 542 ></BODY
 543 ></HTML
 544 >