doc/html/cdl-guide/ref.cdl-package.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_package</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_component"
  26 HREF="ref.cdl-component.html"><LINK
  27 REL="NEXT"
  28 TITLE="cdl_interface"
  29 HREF="ref.cdl-interface.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-component.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-interface.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-PACKAGE"><TT
  86 CLASS="LITERAL"
  87 >cdl_package</TT
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN3272"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Command <TT
  97 CLASS="LITERAL"
  98 >cdl_package</TT
  99 >&nbsp;--&nbsp;Define a package, a component that can be distributed</DIV
 100 ><DIV
 101 CLASS="REFSYNOPSISDIV"
 102 ><A
 103 NAME="AEN3276"><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_package &lt;name&gt; {
 114     &#8230;
 115 }</PRE
 116 ></TD
 117 ></TR
 118 ></TABLE
 119 ></DIV
 120 ><DIV
 121 CLASS="REFSECT1"
 122 ><A
 123 NAME="AEN3278"
 124 ></A
 125 ><H2
 126 >Description</H2
 127 ><P
 128 >A package is a unit of distribution. It is also a configuration option
 129 in that users can choose whether or not a particular package is loaded
 130 into the configuration, and which version of that package should be
 131 loaded. It is also a component in that it can contain additional
 132 components and options in a hierarchy.</P
 133 ><P
 134 >The top-level <SPAN
 135 CLASS="APPLICATION"
 136 >CDL</SPAN
 137 > script for a package should begin with a <TT
 138 CLASS="LITERAL"
 139 >cdl_package</TT
 140 >
 141 command. This can contain most of the properties that can be used in a
 142 <TT
 143 CLASS="LITERAL"
 144 >cdl_option</TT
 145 > command, and a number of additional ones which apply to a
 146 package as a whole. It is also possible to include <TT
 147 CLASS="LITERAL"
 148 >cdl_component</TT
 149 >,
 150 <TT
 151 CLASS="LITERAL"
 152 >cdl_interface</TT
 153 > and <TT
 154 CLASS="LITERAL"
 155 >cdl_option</TT
 156 > commands in the body of a package.
 157 However all configuration entities that occur at the top level of the
 158 script containing the <TT
 159 CLASS="LITERAL"
 160 >cdl_package</TT
 161 > command are automatically placed
 162 below that package in the configuration hierarchy, so putting them
 163 inside the body has no effect.</P
 164 ><P
 165 >The following properties cannot be used in the body of a <TT
 166 CLASS="LITERAL"
 167 >cdl_package</TT
 168 >
 169 command:</P
 170 ><P
 171 ></P
 172 ><DIV
 173 CLASS="VARIABLELIST"
 174 ><DL
 175 ><DT
 176 ><SPAN
 177 CLASS="PROPERTY"
 178 >flavor</SPAN
 179 ></DT
 180 ><DD
 181 ><P
 182 >Packages always have the flavor <TT
 183 CLASS="LITERAL"
 184 >booldata</TT
 185 >.</P
 186 ></DD
 187 ><DT
 188 ><SPAN
 189 CLASS="PROPERTY"
 190 >default_value</SPAN
 191 ></DT
 192 ><DD
 193 ><P
 194 >The value of a package is its version number. This is specified at the
 195 time the package is loaded into the configuration, and cannot be
 196 calculated afterwards. Typically the most recent version of the
 197 package will be loaded.</P
 198 ></DD
 199 ><DT
 200 ><SPAN
 201 CLASS="PROPERTY"
 202 >legal_values</SPAN
 203 ></DT
 204 ><DD
 205 ><P
 206 >The legal values list for a given package is determined by which
 207 versions of that package are installed in the component repository,
 208 and cannot be further constrained in the CDL scripts.</P
 209 ></DD
 210 ><DT
 211 ><SPAN
 212 CLASS="PROPERTY"
 213 >calculated</SPAN
 214 ></DT
 215 ><DD
 216 ><P
 217 >The value of a package is always selected at the time that it is
 218 loaded into the configuration, and cannot be re-calculated afterwards.</P
 219 ></DD
 220 ><DT
 221 ><SPAN
 222 CLASS="PROPERTY"
 223 >script</SPAN
 224 ></DT
 225 ><DD
 226 ><P
 227 >This would be redundant since the CDL script containing the
 228 <TT
 229 CLASS="LITERAL"
 230 >cdl_package</TT
 231 > command acts as that package's script.</P
 232 ></DD
 233 ></DL
 234 ></DIV
 235 ><P
 236 ><TT
 237 CLASS="LITERAL"
 238 >cdl_package</TT
 239 > is implemented as a Tcl command that takes two
 240 arguments, a name and a body. The name must be a valid C preprocessor
 241 identifier: a sequence of upper or lower case letters, digits or
 242 underscores, starting with a non-digit character; identifiers
 243 beginning with an underscore should normally be avoided because they
 244 may clash with system packages or with identifiers reserved for use by
 245 the compiler. Packages should always have unique names within a given
 246 component repository. For a recommended naming convention see <A
 247 HREF="package.contents.html"
 248 >the Section called <I
 249 >Package Contents and Layout</I
 250 > in Chapter 2</A
 251 >.</P
 252 ><P
 253 >The second argument to <TT
 254 CLASS="LITERAL"
 255 >cdl_package</TT
 256 > is a body of properties and other
 257 commands, typically surrounded by braces so that the Tcl interpreter
 258 treats it as a single argument. This body will be processed by a
 259 recursive invocation of the Tcl interpreter, extended with additional
 260 commands for the various properties that are allowed inside a
 261 <TT
 262 CLASS="LITERAL"
 263 >cdl_package</TT
 264 >. The valid commands are:</P
 265 ><P
 266 ></P
 267 ><DIV
 268 CLASS="VARIABLELIST"
 269 ><DL
 270 ><DT
 271 ><A
 272 HREF="ref.active-if.html"
 273 ><SPAN
 274 CLASS="PROPERTY"
 275 >active_if</SPAN
 276 ></A
 277 ></DT
 278 ><DD
 279 ><P
 280 >Allow additional control over the active state of this package.</P
 281 ></DD
 282 ><DT
 283 ><A
 284 HREF="ref.cdl-component.html"
 285 ><TT
 286 CLASS="LITERAL"
 287 >cdl_component</TT
 288 ></A
 289 ></DT
 290 ><DD
 291 ><P
 292 >Define a component which should appear immediately below this package
 293 in the configuration hierarchy.</P
 294 ></DD
 295 ><DT
 296 ><A
 297 HREF="ref.cdl-interface.html"
 298 ><TT
 299 CLASS="LITERAL"
 300 >cdl_interface</TT
 301 ></A
 302 ></DT
 303 ><DD
 304 ><P
 305 >Define an interface which should appear immediately below this
 306 package in the configuration hierarchy.</P
 307 ></DD
 308 ><DT
 309 ><A
 310 HREF="ref.cdl-option.html"
 311 ><TT
 312 CLASS="LITERAL"
 313 >cdl_option</TT
 314 ></A
 315 ></DT
 316 ><DD
 317 ><P
 318 >Define an option which should appear immediately below
 319 this package in the configuration hierarchy.</P
 320 ></DD
 321 ><DT
 322 ><A
 323 HREF="ref.compile.html"
 324 ><SPAN
 325 CLASS="PROPERTY"
 326 >compile</SPAN
 327 ></A
 328 ></DT
 329 ><DD
 330 ><P
 331 >List the source files that should be built for this package.</P
 332 ></DD
 333 ><DT
 334 ><A
 335 HREF="ref.define.html"
 336 ><SPAN
 337 CLASS="PROPERTY"
 338 >define</SPAN
 339 ></A
 340 ></DT
 341 ><DD
 342 ><P
 343 >Specify additional <TT
 344 CLASS="LITERAL"
 345 >#define</TT
 346 > symbols that should go
 347 into the package's configuration header file.</P
 348 ></DD
 349 ><DT
 350 ><A
 351 HREF="ref.define-format.html"
 352 ><SPAN
 353 CLASS="PROPERTY"
 354 >define_format</SPAN
 355 ></A
 356 ></DT
 357 ><DD
 358 ><P
 359 >Control how the package's value will appear in the global
 360 configuration header file <TT
 361 CLASS="FILENAME"
 362 >pkgconf/system.h</TT
 363 ></P
 364 ></DD
 365 ><DT
 366 ><A
 367 HREF="ref.define-header.html"
 368 ><SPAN
 369 CLASS="PROPERTY"
 370 >define_header</SPAN
 371 ></A
 372 ></DT
 373 ><DD
 374 ><P
 375 >Specify the configuration header file that will be generated for this package.</P
 376 ></DD
 377 ><DT
 378 ><A
 379 HREF="ref.define-proc.html"
 380 ><SPAN
 381 CLASS="PROPERTY"
 382 >define_proc</SPAN
 383 ></A
 384 ></DT
 385 ><DD
 386 ><P
 387 >Use a fragment of Tcl code to output additional data to
 388 configuration header files.</P
 389 ></DD
 390 ><DT
 391 ><A
 392 HREF="ref.description.html"
 393 ><SPAN
 394 CLASS="PROPERTY"
 395 >description</SPAN
 396 ></A
 397 ></DT
 398 ><DD
 399 ><P
 400 >Provide a textual description for this component.</P
 401 ></DD
 402 ><DT
 403 ><A
 404 HREF="ref.display.html"
 405 ><SPAN
 406 CLASS="PROPERTY"
 407 >display</SPAN
 408 ></A
 409 ></DT
 410 ><DD
 411 ><P
 412 >Provide a short string describing this component.</P
 413 ></DD
 414 ><DT
 415 ><A
 416 HREF="ref.doc.html"
 417 ><SPAN
 418 CLASS="PROPERTY"
 419 >doc</SPAN
 420 ></A
 421 ></DT
 422 ><DD
 423 ><P
 424 >The location of on-line documentation for this component.</P
 425 ></DD
 426 ><DT
 427 ><A
 428 HREF="ref.hardware.html"
 429 ><SPAN
 430 CLASS="PROPERTY"
 431 >hardware</SPAN
 432 ></A
 433 ></DT
 434 ><DD
 435 ><P
 436 >This package is tied to specific hardware.</P
 437 ></DD
 438 ><DT
 439 ><A
 440 HREF="ref.if-define.html"
 441 ><SPAN
 442 CLASS="PROPERTY"
 443 >if_define</SPAN
 444 ></A
 445 ></DT
 446 ><DD
 447 ><P
 448 >Output a common preprocessor construct to a configuration header file. </P
 449 ></DD
 450 ><DT
 451 ><A
 452 HREF="ref.implements.html"
 453 ><SPAN
 454 CLASS="PROPERTY"
 455 >implements</SPAN
 456 ></A
 457 ></DT
 458 ><DD
 459 ><P
 460 >Enabling this component provides one instance of a more general
 461 interface. </P
 462 ></DD
 463 ><DT
 464 ><A
 465 HREF="ref.include-dir.html"
 466 ><SPAN
 467 CLASS="PROPERTY"
 468 >include_dir</SPAN
 469 ></A
 470 ></DT
 471 ><DD
 472 ><P
 473 >Specify the desired location of this package's exported header files in
 474 the install tree.</P
 475 ></DD
 476 ><DT
 477 ><A
 478 HREF="ref.include-files.html"
 479 ><SPAN
 480 CLASS="PROPERTY"
 481 >include_files</SPAN
 482 ></A
 483 ></DT
 484 ><DD
 485 ><P
 486 >List the header files that are exported by this package.</P
 487 ></DD
 488 ><DT
 489 ><A
 490 HREF="ref.library.html"
 491 ><SPAN
 492 CLASS="PROPERTY"
 493 >library</SPAN
 494 ></A
 495 ></DT
 496 ><DD
 497 ><P
 498 >Specify which library should contain the object files
 499 generated by building this package.</P
 500 ></DD
 501 ><DT
 502 ><A
 503 HREF="ref.make.html"
 504 ><SPAN
 505 CLASS="PROPERTY"
 506 >make</SPAN
 507 ></A
 508 ></DT
 509 ><DD
 510 ><P
 511 >An additional custom build step associated with this component, resulting
 512 in a target that should not go directly into a library.</P
 513 ></DD
 514 ><DT
 515 ><A
 516 HREF="ref.make-object.html"
 517 ><SPAN
 518 CLASS="PROPERTY"
 519 >make_object</SPAN
 520 ></A
 521 ></DT
 522 ><DD
 523 ><P
 524 >An additional custom build step associated with this component, resulting
 525 in an object file that should go into a library.</P
 526 ></DD
 527 ><DT
 528 ><A
 529 HREF="ref.no-define.html"
 530 ><SPAN
 531 CLASS="PROPERTY"
 532 >no_define</SPAN
 533 ></A
 534 ></DT
 535 ><DD
 536 ><P
 537 >Suppress the normal generation of the package's
 538 <TT
 539 CLASS="LITERAL"
 540 >#define</TT
 541 > in the global configuration header file
 542 <TT
 543 CLASS="FILENAME"
 544 >pkgconf/system.h</TT
 545 >.</P
 546 ></DD
 547 ><DT
 548 ><A
 549 HREF="ref.parent.html"
 550 ><SPAN
 551 CLASS="PROPERTY"
 552 >parent</SPAN
 553 ></A
 554 ></DT
 555 ><DD
 556 ><P
 557 >Control the location of this package in the configuration hierarchy. </P
 558 ></DD
 559 ><DT
 560 ><A
 561 HREF="ref.requires.html"
 562 ><SPAN
 563 CLASS="PROPERTY"
 564 >requires</SPAN
 565 ></A
 566 ></DT
 567 ><DD
 568 ><P
 569 >List constraints that the configuration should satisfy if this package is
 570 active.</P
 571 ></DD
 572 ></DL
 573 ></DIV
 574 ></DIV
 575 ><DIV
 576 CLASS="REFSECT1"
 577 ><A
 578 NAME="AEN3468"
 579 ></A
 580 ><H2
 581 >Example</H2
 582 ><TABLE
 583 BORDER="5"
 584 BGCOLOR="#E0E0F0"
 585 WIDTH="70%"
 586 ><TR
 587 ><TD
 588 ><PRE
 589 CLASS="PROGRAMLISTING"
 590 >cdl_package CYGPKG_INFRA {
 591     display       "Infrastructure"
 592     include_dir   cyg/infra
 593     description   "
 594         Common types and useful macros.
 595         Tracing and assertion facilities.
 596         Package startup options."
 597
 598     compile startup.cxx prestart.cxx pkgstart.cxx userstart.cxx      \
 599             dummyxxmain.cxx null.cxx simple.cxx fancy.cxx buffer.cxx \
 600             diag.cxx tcdiag.cxx memcpy.c memset.c delete.cxx
 601 }&#13;</PRE
 602 ></TD
 603 ></TR
 604 ></TABLE
 605 ></DIV
 606 ><DIV
 607 CLASS="REFSECT1"
 608 ><A
 609 NAME="AEN3471"
 610 ></A
 611 ><H2
 612 >See Also</H2
 613 ><P
 614 >Command <A
 615 HREF="ref.cdl-option.html"
 616 ><TT
 617 CLASS="LITERAL"
 618 >cdl_option</TT
 619 ></A
 620 >,
 621 command <A
 622 HREF="ref.cdl-component.html"
 623 ><TT
 624 CLASS="LITERAL"
 625 >cdl_component</TT
 626 ></A
 627 >,
 628 command <A
 629 HREF="ref.cdl-interface.html"
 630 ><TT
 631 CLASS="LITERAL"
 632 >cdl_interface</TT
 633 ></A
 634 >.</P
 635 ></DIV
 636 ><DIV
 637 CLASS="NAVFOOTER"
 638 ><HR
 639 ALIGN="LEFT"
 640 WIDTH="100%"><TABLE
 641 SUMMARY="Footer navigation table"
 642 WIDTH="100%"
 643 BORDER="0"
 644 CELLPADDING="0"
 645 CELLSPACING="0"
 646 ><TR
 647 ><TD
 648 WIDTH="33%"
 649 ALIGN="left"
 650 VALIGN="top"
 651 ><A
 652 HREF="ref.cdl-component.html"
 653 ACCESSKEY="P"
 654 >Prev</A
 655 ></TD
 656 ><TD
 657 WIDTH="34%"
 658 ALIGN="center"
 659 VALIGN="top"
 660 ><A
 661 HREF="cdl-guide.html"
 662 ACCESSKEY="H"
 663 >Home</A
 664 ></TD
 665 ><TD
 666 WIDTH="33%"
 667 ALIGN="right"
 668 VALIGN="top"
 669 ><A
 670 HREF="ref.cdl-interface.html"
 671 ACCESSKEY="N"
 672 >Next</A
 673 ></TD
 674 ></TR
 675 ><TR
 676 ><TD
 677 WIDTH="33%"
 678 ALIGN="left"
 679 VALIGN="top"
 680 ><TT
 681 CLASS="LITERAL"
 682 >cdl_component</TT
 683 ></TD
 684 ><TD
 685 WIDTH="34%"
 686 ALIGN="center"
 687 VALIGN="top"
 688 ><A
 689 HREF="reference.html"
 690 ACCESSKEY="U"
 691 >Up</A
 692 ></TD
 693 ><TD
 694 WIDTH="33%"
 695 ALIGN="right"
 696 VALIGN="top"
 697 ><TT
 698 CLASS="LITERAL"
 699 >cdl_interface</TT
 700 ></TD
 701 ></TR
 702 ></TABLE
 703 ></DIV
 704 ></BODY
 705 ></HTML
 706 >