doc/html/cdl-guide/ref.cdl-component.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 >cdl_component</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_option"
  26 HREF="ref.cdl-option.html"><LINK
  27 REL="NEXT"
  28 TITLE="cdl_package"
  29 HREF="ref.cdl-package.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-option.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.cdl-package.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.CDL-COMPONENT"><TT
  86 CLASS="LITERAL"
  87 >cdl_component</TT
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN3091"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Command <TT
  97 CLASS="LITERAL"
  98 >cdl_component</TT
  99 >&nbsp;--&nbsp;Define a component, a collection of configuration options</DIV
 100 ><DIV
 101 CLASS="REFSYNOPSISDIV"
 102 ><A
 103 NAME="AEN3095"><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_component &lt;name&gt; {
 114     &#8230;
 115 }</PRE
 116 ></TD
 117 ></TR
 118 ></TABLE
 119 ></DIV
 120 ><DIV
 121 CLASS="REFSECT1"
 122 ><A
 123 NAME="AEN3097"
 124 ></A
 125 ><H2
 126 >Description</H2
 127 ><P
 128 >A component is a configuration option that can contain additional
 129 options and sub-components. The body of a <TT
 130 CLASS="LITERAL"
 131 >cdl_component</TT
 132 > can contain
 133 the same properties as that of a <TT
 134 CLASS="LITERAL"
 135 >cdl_option</TT
 136 >. There is an additional
 137 property, <SPAN
 138 CLASS="PROPERTY"
 139 >script</SPAN
 140 > which allows configuration data to be split into
 141 multiple files. It is also possible for a component body to include
 142 <TT
 143 CLASS="LITERAL"
 144 >cdl_component</TT
 145 >, <TT
 146 CLASS="LITERAL"
 147 >cdl_option</TT
 148 > and <TT
 149 CLASS="LITERAL"
 150 >cdl_interface</TT
 151 > entities that should
 152 go below this component in the configuration hierarchy.</P
 153 ><P
 154 ><TT
 155 CLASS="LITERAL"
 156 >cdl_component</TT
 157 > is implemented as a Tcl command that takes two
 158 arguments, a name and a body. The name must be a valid C preprocessor
 159 identifier: a sequence of upper or lower case letters, digits or
 160 underscores, starting with a non-digit character; identifiers
 161 beginning with an underscore should normally be avoided because they
 162 may clash with system packages or with identifiers reserved for use by
 163 the compiler. Within a single configuration, names must be unique. If
 164 a configuration contained two packages which defined the same entity
 165 <TT
 166 CLASS="LITERAL"
 167 >CYGIMP_SOME_OPTION</TT
 168 >, any references to that entity
 169 in a <SPAN
 170 CLASS="PROPERTY"
 171 >requires</SPAN
 172 > property or any other expression would be ambiguous.
 173 It is possible for a given name to be used by two different packages
 174 if those packages should never be loaded into a single configuration.
 175 For example, architectural HAL packages are allowed to re-use certain
 176 names because a single configuration cannot target two different
 177 architectures. For a recommended naming convention see <A
 178 HREF="package.contents.html"
 179 >the Section called <I
 180 >Package Contents and Layout</I
 181 > in Chapter 2</A
 182 >.</P
 183 ><P
 184 >The second argument to <TT
 185 CLASS="LITERAL"
 186 >cdl_component</TT
 187 > is a body of properties and
 188 other commands, typically surrounded by braces so that the Tcl
 189 interpreter treats it as a single argument. This body will be
 190 processed by a recursive invocation of the Tcl interpreter, extended
 191 with additional commands for the various properties that are allowed
 192 inside a <TT
 193 CLASS="LITERAL"
 194 >cdl_component</TT
 195 >. The valid commands are:</P
 196 ><P
 197 ></P
 198 ><DIV
 199 CLASS="VARIABLELIST"
 200 ><DL
 201 ><DT
 202 ><A
 203 HREF="ref.active-if.html"
 204 ><SPAN
 205 CLASS="PROPERTY"
 206 >active_if</SPAN
 207 ></A
 208 ></DT
 209 ><DD
 210 ><P
 211 >Allow additional control over the active state of this component.</P
 212 ></DD
 213 ><DT
 214 ><A
 215 HREF="ref.calculated.html"
 216 ><SPAN
 217 CLASS="PROPERTY"
 218 >calculated</SPAN
 219 ></A
 220 ></DT
 221 ><DD
 222 ><P
 223 >The component's value is not directly user-modifiable, it is calculated
 224 using a suitable CDL expression.</P
 225 ></DD
 226 ><DT
 227 ><A
 228 HREF="ref.cdl-component.html"
 229 ><TT
 230 CLASS="LITERAL"
 231 >cdl_component</TT
 232 ></A
 233 ></DT
 234 ><DD
 235 ><P
 236 >Define a sub-component.</P
 237 ></DD
 238 ><DT
 239 ><A
 240 HREF="ref.cdl-interface.html"
 241 ><TT
 242 CLASS="LITERAL"
 243 >cdl_interface</TT
 244 ></A
 245 ></DT
 246 ><DD
 247 ><P
 248 >Define an interface which should appear immediately below this
 249 component in the configuration hierarchy.</P
 250 ></DD
 251 ><DT
 252 ><A
 253 HREF="ref.cdl-option.html"
 254 ><TT
 255 CLASS="LITERAL"
 256 >cdl_option</TT
 257 ></A
 258 ></DT
 259 ><DD
 260 ><P
 261 >Define a configuration option which should appear immediately below
 262 this component in the configuration hierarchy.</P
 263 ></DD
 264 ><DT
 265 ><A
 266 HREF="ref.compile.html"
 267 ><SPAN
 268 CLASS="PROPERTY"
 269 >compile</SPAN
 270 ></A
 271 ></DT
 272 ><DD
 273 ><P
 274 >List the source files that should be built if this component is active
 275 and enabled.</P
 276 ></DD
 277 ><DT
 278 ><A
 279 HREF="ref.default-value.html"
 280 ><SPAN
 281 CLASS="PROPERTY"
 282 >default_value</SPAN
 283 ></A
 284 ></DT
 285 ><DD
 286 ><P
 287 >Provide a default value for this component using a CDL expression.</P
 288 ></DD
 289 ><DT
 290 ><A
 291 HREF="ref.define.html"
 292 ><SPAN
 293 CLASS="PROPERTY"
 294 >define</SPAN
 295 ></A
 296 ></DT
 297 ><DD
 298 ><P
 299 >Specify additional <TT
 300 CLASS="LITERAL"
 301 >#define</TT
 302 > symbols that should go
 303 into the owning package's configuration header file.</P
 304 ></DD
 305 ><DT
 306 ><A
 307 HREF="ref.define-format.html"
 308 ><SPAN
 309 CLASS="PROPERTY"
 310 >define_format</SPAN
 311 ></A
 312 ></DT
 313 ><DD
 314 ><P
 315 >Control how the component's value will appear in the configuration header
 316 file.</P
 317 ></DD
 318 ><DT
 319 ><A
 320 HREF="ref.define-proc.html"
 321 ><SPAN
 322 CLASS="PROPERTY"
 323 >define_proc</SPAN
 324 ></A
 325 ></DT
 326 ><DD
 327 ><P
 328 >Use a fragment of Tcl code to output additional data to
 329 configuration header files.</P
 330 ></DD
 331 ><DT
 332 ><A
 333 HREF="ref.description.html"
 334 ><SPAN
 335 CLASS="PROPERTY"
 336 >description</SPAN
 337 ></A
 338 ></DT
 339 ><DD
 340 ><P
 341 >Provide a textual description for this component.</P
 342 ></DD
 343 ><DT
 344 ><A
 345 HREF="ref.display.html"
 346 ><SPAN
 347 CLASS="PROPERTY"
 348 >display</SPAN
 349 ></A
 350 ></DT
 351 ><DD
 352 ><P
 353 >Provide a short string describing this component.</P
 354 ></DD
 355 ><DT
 356 ><A
 357 HREF="ref.doc.html"
 358 ><SPAN
 359 CLASS="PROPERTY"
 360 >doc</SPAN
 361 ></A
 362 ></DT
 363 ><DD
 364 ><P
 365 >The location of on-line documentation for this component.</P
 366 ></DD
 367 ><DT
 368 ><A
 369 HREF="ref.flavor.html"
 370 ><SPAN
 371 CLASS="PROPERTY"
 372 >flavor</SPAN
 373 ></A
 374 ></DT
 375 ><DD
 376 ><P
 377 >Specify the nature of this component.</P
 378 ></DD
 379 ><DT
 380 ><A
 381 HREF="ref.if-define.html"
 382 ><SPAN
 383 CLASS="PROPERTY"
 384 >if_define</SPAN
 385 ></A
 386 ></DT
 387 ><DD
 388 ><P
 389 >Output a common preprocessor construct to a configuration header file. </P
 390 ></DD
 391 ><DT
 392 ><A
 393 HREF="ref.implements.html"
 394 ><SPAN
 395 CLASS="PROPERTY"
 396 >implements</SPAN
 397 ></A
 398 ></DT
 399 ><DD
 400 ><P
 401 >Enabling this component provides one instance of a more general
 402 interface. </P
 403 ></DD
 404 ><DT
 405 ><A
 406 HREF="ref.legal-values.html"
 407 ><SPAN
 408 CLASS="PROPERTY"
 409 >legal_values</SPAN
 410 ></A
 411 ></DT
 412 ><DD
 413 ><P
 414 >Impose constraints on the possible values for this component.</P
 415 ></DD
 416 ><DT
 417 ><A
 418 HREF="ref.make.html"
 419 ><SPAN
 420 CLASS="PROPERTY"
 421 >make</SPAN
 422 ></A
 423 ></DT
 424 ><DD
 425 ><P
 426 >An additional custom build step associated with this component, resulting
 427 in a target that should not go directly into a library.</P
 428 ></DD
 429 ><DT
 430 ><A
 431 HREF="ref.make-object.html"
 432 ><SPAN
 433 CLASS="PROPERTY"
 434 >make_object</SPAN
 435 ></A
 436 ></DT
 437 ><DD
 438 ><P
 439 >An additional custom build step associated with this component, resulting
 440 in an object file that should go into a library.</P
 441 ></DD
 442 ><DT
 443 ><A
 444 HREF="ref.no-define.html"
 445 ><SPAN
 446 CLASS="PROPERTY"
 447 >no_define</SPAN
 448 ></A
 449 ></DT
 450 ><DD
 451 ><P
 452 >Suppress the normal generation of a preprocessor
 453 <TT
 454 CLASS="LITERAL"
 455 >#define</TT
 456 > symbol in a configuration header file.</P
 457 ></DD
 458 ><DT
 459 ><A
 460 HREF="ref.parent.html"
 461 ><SPAN
 462 CLASS="PROPERTY"
 463 >parent</SPAN
 464 ></A
 465 ></DT
 466 ><DD
 467 ><P
 468 >Control the location of this component in the configuration hierarchy. </P
 469 ></DD
 470 ><DT
 471 ><A
 472 HREF="ref.requires.html"
 473 ><SPAN
 474 CLASS="PROPERTY"
 475 >requires</SPAN
 476 ></A
 477 ></DT
 478 ><DD
 479 ><P
 480 >List constraints that the configuration should satisfy if this component is
 481 active and enabled.</P
 482 ></DD
 483 ><DT
 484 ><A
 485 HREF="ref.script.html"
 486 ><SPAN
 487 CLASS="PROPERTY"
 488 >script</SPAN
 489 ></A
 490 ></DT
 491 ><DD
 492 ><P
 493 >Include additional configuration information from another
 494 CDL script</P
 495 ></DD
 496 ></DL
 497 ></DIV
 498 ></DIV
 499 ><DIV
 500 CLASS="REFSECT1"
 501 ><A
 502 NAME="AEN3255"
 503 ></A
 504 ><H2
 505 >Example</H2
 506 ><P
 507 ><TABLE
 508 BORDER="5"
 509 BGCOLOR="#E0E0F0"
 510 WIDTH="70%"
 511 ><TR
 512 ><TD
 513 ><PRE
 514 CLASS="PROGRAMLISTING"
 515 >cdl_component CYGDBG_USE_ASSERTS {
 516     display       "Use asserts"
 517     default_value 1
 518     description   "
 519         If this component is enabled, assertions in the code are
 520         tested at run-time. Assert functions (CYG_ASSERT()) are
 521         defined in 'include/cyg/infra/cyg_ass.h' within the 'install'
 522         tree. If the component is disabled, these result in no
 523         additional object code and no checking of the asserted
 524         conditions."
 525     script        assert.cdl
 526 }</PRE
 527 ></TD
 528 ></TR
 529 ></TABLE
 530 ></P
 531 ></DIV
 532 ><DIV
 533 CLASS="REFSECT1"
 534 ><A
 535 NAME="AEN3259"
 536 ></A
 537 ><H2
 538 >See Also</H2
 539 ><P
 540 >Command <A
 541 HREF="ref.cdl-option.html"
 542 ><TT
 543 CLASS="LITERAL"
 544 >cdl_option</TT
 545 ></A
 546 >,
 547 command <A
 548 HREF="ref.cdl-package.html"
 549 ><TT
 550 CLASS="LITERAL"
 551 >cdl_package</TT
 552 ></A
 553 >,
 554 command <A
 555 HREF="ref.cdl-interface.html"
 556 ><TT
 557 CLASS="LITERAL"
 558 >cdl_interface</TT
 559 ></A
 560 >.</P
 561 ></DIV
 562 ><DIV
 563 CLASS="NAVFOOTER"
 564 ><HR
 565 ALIGN="LEFT"
 566 WIDTH="100%"><TABLE
 567 SUMMARY="Footer navigation table"
 568 WIDTH="100%"
 569 BORDER="0"
 570 CELLPADDING="0"
 571 CELLSPACING="0"
 572 ><TR
 573 ><TD
 574 WIDTH="33%"
 575 ALIGN="left"
 576 VALIGN="top"
 577 ><A
 578 HREF="ref.cdl-option.html"
 579 ACCESSKEY="P"
 580 >Prev</A
 581 ></TD
 582 ><TD
 583 WIDTH="34%"
 584 ALIGN="center"
 585 VALIGN="top"
 586 ><A
 587 HREF="cdl-guide.html"
 588 ACCESSKEY="H"
 589 >Home</A
 590 ></TD
 591 ><TD
 592 WIDTH="33%"
 593 ALIGN="right"
 594 VALIGN="top"
 595 ><A
 596 HREF="ref.cdl-package.html"
 597 ACCESSKEY="N"
 598 >Next</A
 599 ></TD
 600 ></TR
 601 ><TR
 602 ><TD
 603 WIDTH="33%"
 604 ALIGN="left"
 605 VALIGN="top"
 606 ><TT
 607 CLASS="LITERAL"
 608 >cdl_option</TT
 609 ></TD
 610 ><TD
 611 WIDTH="34%"
 612 ALIGN="center"
 613 VALIGN="top"
 614 ><A
 615 HREF="reference.html"
 616 ACCESSKEY="U"
 617 >Up</A
 618 ></TD
 619 ><TD
 620 WIDTH="33%"
 621 ALIGN="right"
 622 VALIGN="top"
 623 ><TT
 624 CLASS="LITERAL"
 625 >cdl_package</TT
 626 ></TD
 627 ></TR
 628 ></TABLE
 629 ></DIV
 630 ></BODY
 631 ></HTML
 632 >