doc/html/cdl-guide/language.properties.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 Properties</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="The CDL Language"
  23 HREF="language.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="CDL Commands"
  26 HREF="language.commands.html"><LINK
  27 REL="NEXT"
  28 TITLE="Option Naming Convention"
  29 HREF="language.naming.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  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="language.commands.html"
  61 ACCESSKEY="P"
  62 >Prev</A
  63 ></TD
  64 ><TD
  65 WIDTH="80%"
  66 ALIGN="center"
  67 VALIGN="bottom"
  68 >Chapter 3. The CDL Language</TD
  69 ><TD
  70 WIDTH="10%"
  71 ALIGN="right"
  72 VALIGN="bottom"
  73 ><A
  74 HREF="language.naming.html"
  75 ACCESSKEY="N"
  76 >Next</A
  77 ></TD
  78 ></TR
  79 ></TABLE
  80 ><HR
  81 ALIGN="LEFT"
  82 WIDTH="100%"></DIV
  83 ><DIV
  84 CLASS="SECT1"
  85 ><H1
  86 CLASS="SECT1"
  87 ><A
  88 NAME="LANGUAGE.PROPERTIES">CDL Properties</H1
  89 ><P
  90 >Each package, component, option, and interface has a body of
  91 properties, which provide the component framework with information
  92 about how to handle each option. For example there is a property for a
  93 descriptive text message which can be displayed to a user who is
  94 trying to figure out just what effect manipulating the option would
  95 have on the target application. There is another property for the
  96 default value, for example whether a particular option should be
  97 enabled or disabled by default.</P
  98 ><P
  99 >All of the properties are optional, it is legal to define a
 100 configuration option which has an empty body. However some properties
 101 are more optional than others: users will not appreciate having to
 102 manipulate an option if they are not given any sort of description or
 103 documentation. Other properties are intended only for very specific
 104 purposes, for example <SPAN
 105 CLASS="PROPERTY"
 106 >make_object</SPAN
 107 > and <SPAN
 108 CLASS="PROPERTY"
 109 >include_files</SPAN
 110 >, and are used
 111 only rarely.</P
 112 ><P
 113 >Because different properties serve very different purposes, their
 114 syntax is not as uniform as the top-level commands. Some properties
 115 take no arguments at all. Other properties take a single argument such
 116 as a description string, or a list of arguments such as a <SPAN
 117 CLASS="PROPERTY"
 118 >compile</SPAN
 119 >
 120 property which specifies the file or files that should be compiled if
 121 a given option is active and enabled. The <SPAN
 122 CLASS="PROPERTY"
 123 >define_proc</SPAN
 124 > property takes
 125 as argument a snippet of <SPAN
 126 CLASS="APPLICATION"
 127 >Tcl</SPAN
 128 > code. The <SPAN
 129 CLASS="PROPERTY"
 130 >active_if</SPAN
 131 >, <SPAN
 132 CLASS="PROPERTY"
 133 >calculated</SPAN
 134 >,
 135 <SPAN
 136 CLASS="PROPERTY"
 137 >default_value</SPAN
 138 >, <SPAN
 139 CLASS="PROPERTY"
 140 >legal_values</SPAN
 141 > and <SPAN
 142 CLASS="PROPERTY"
 143 >requires</SPAN
 144 > properties take various
 145 expressions. Additional properties may be defined in future which take
 146 new kinds of arguments.</P
 147 ><P
 148 >All property parsing code supports options for every property,
 149 although at present the majority of properties do not yet take any
 150 options. Any initial arguments that begin with a hyphen character
 151 <TT
 152 CLASS="LITERAL"
 153 >-</TT
 154 > will be interpreted as an option, for example:</P
 155 ><TABLE
 156 BORDER="5"
 157 BGCOLOR="#E0E0F0"
 158 WIDTH="70%"
 159 ><TR
 160 ><TD
 161 ><PRE
 162 CLASS="PROGRAMLISTING"
 163 >cdl_package CYGPKG_HAL_ARM {
 164     &#8230;
 165     make -priority 1 {
 166         &#8230;
 167     }
 168 }</PRE
 169 ></TD
 170 ></TR
 171 ></TABLE
 172 ><P
 173 >If the option involves additional data, as for the
 174 <TT
 175 CLASS="LITERAL"
 176 >-priority</TT
 177 > example above, then this can be written
 178 as either <TT
 179 CLASS="LITERAL"
 180 >-priority=1</TT
 181 > or as
 182 <TT
 183 CLASS="LITERAL"
 184 >-priority&nbsp;1</TT
 185 >. On occasion the option parsing
 186 code can get in the way, for example:</P
 187 ><TABLE
 188 BORDER="5"
 189 BGCOLOR="#E0E0F0"
 190 WIDTH="70%"
 191 ><TR
 192 ><TD
 193 ><PRE
 194 CLASS="PROGRAMLISTING"
 195 >cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_STATE {
 196     &#8230;
 197     legal_values -1 to 1
 198     default_value -1
 199 }</PRE
 200 ></TD
 201 ></TR
 202 ></TABLE
 203 ><P
 204 >Neither the <SPAN
 205 CLASS="PROPERTY"
 206 >legal_values</SPAN
 207 > nor the <SPAN
 208 CLASS="PROPERTY"
 209 >default_value</SPAN
 210 > property will
 211 accept <TT
 212 CLASS="LITERAL"
 213 >-1</TT
 214 > as a valid option, so this will result in
 215 syntax errors when the <SPAN
 216 CLASS="APPLICATION"
 217 >CDL</SPAN
 218 > script is read in by the component
 219 framework. To avoid problems, the option parsing code will recognize
 220 the string <TT
 221 CLASS="LITERAL"
 222 >--</TT
 223 > and will not attempt to interpret any
 224 subsequent arguments. Hence this option should be written as:</P
 225 ><TABLE
 226 BORDER="5"
 227 BGCOLOR="#E0E0F0"
 228 WIDTH="70%"
 229 ><TR
 230 ><TD
 231 ><PRE
 232 CLASS="PROGRAMLISTING"
 233 >cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_STATE {
 234     &#8230;
 235     legal_values  -- -1 to 1
 236     default_value -- -1
 237 }</PRE
 238 ></TD
 239 ></TR
 240 ></TABLE
 241 ><P
 242 >The property parsing code involves a recursive invocation of the Tcl
 243 interpreter that is used to parse the top-level commands. This means
 244 that some characters in the body of an option will be treated
 245 specially. The <TT
 246 CLASS="LITERAL"
 247 >#</TT
 248 > character can be used for
 249 comments. The backslash character <TT
 250 CLASS="LITERAL"
 251 >\</TT
 252 >, the
 253 dollar character <TT
 254 CLASS="LITERAL"
 255 >$</TT
 256 >, square brackets
 257 <TT
 258 CLASS="LITERAL"
 259 >[</TT
 260 > and <TT
 261 CLASS="LITERAL"
 262 >]</TT
 263 >, braces
 264 <TT
 265 CLASS="LITERAL"
 266 >{</TT
 267 > and <TT
 268 CLASS="LITERAL"
 269 >}</TT
 270 >, and the quote character
 271 <TT
 272 CLASS="LITERAL"
 273 >"</TT
 274 > may all receive special treatment. Most of the
 275 time this is not a problem because these characters are not useful for
 276 most properties. On occasion having a <SPAN
 277 CLASS="APPLICATION"
 278 >Tcl</SPAN
 279 > interpreter around
 280 performing the parser can be very powerful. For more details of
 281 how the presence of a <SPAN
 282 CLASS="APPLICATION"
 283 >Tcl</SPAN
 284 > interpreter can affect <SPAN
 285 CLASS="APPLICATION"
 286 >CDL</SPAN
 287 > scripts,
 288 see <A
 289 HREF="language.tcl.html"
 290 >the Section called <I
 291 >An Introduction to Tcl</I
 292 ></A
 293 >.</P
 294 ><P
 295 >Many of the properties can be used in any of <TT
 296 CLASS="LITERAL"
 297 >cdl_package</TT
 298 >,
 299 <TT
 300 CLASS="LITERAL"
 301 >cdl_component</TT
 302 >, <TT
 303 CLASS="LITERAL"
 304 >cdl_option</TT
 305 > or <TT
 306 CLASS="LITERAL"
 307 >cdl_interface</TT
 308 >. Other properties are
 309 more specific. The <SPAN
 310 CLASS="PROPERTY"
 311 >script</SPAN
 312 > property is only relevant to components.
 313 The <SPAN
 314 CLASS="PROPERTY"
 315 >define_header</SPAN
 316 >, <SPAN
 317 CLASS="PROPERTY"
 318 >hardware</SPAN
 319 >, <SPAN
 320 CLASS="PROPERTY"
 321 >include_dir</SPAN
 322 >, <SPAN
 323 CLASS="PROPERTY"
 324 >include_files</SPAN
 325 >, and
 326 <SPAN
 327 CLASS="PROPERTY"
 328 >library</SPAN
 329 > properties apply to a package as a whole, so can only occur
 330 in the body of a <TT
 331 CLASS="LITERAL"
 332 >cdl_package</TT
 333 > command. The <SPAN
 334 CLASS="PROPERTY"
 335 >calculated</SPAN
 336 >,
 337 <SPAN
 338 CLASS="PROPERTY"
 339 >default_value</SPAN
 340 >, <SPAN
 341 CLASS="PROPERTY"
 342 >legal_values</SPAN
 343 > and <SPAN
 344 CLASS="PROPERTY"
 345 >flavor</SPAN
 346 > properties are not
 347 relevant to packages, as will be explained later. The <SPAN
 348 CLASS="PROPERTY"
 349 >calculated</SPAN
 350 > and
 351 <SPAN
 352 CLASS="PROPERTY"
 353 >default_value</SPAN
 354 > properties are also not relevant to interfaces.</P
 355 ><P
 356 >This section lists the various properties, grouped by purpose. Each
 357 property also has a full reference page in <A
 358 HREF="reference.html"
 359 >Chapter 5</A
 360 >.
 361 Properties related to values and expressions are described in more
 362 detail in <A
 363 HREF="language.values.html"
 364 >the Section called <I
 365 >Values and Expressions</I
 366 ></A
 367 >. Properties related to
 368 header file generation and to the build process are described in
 369 <A
 370 HREF="build.html"
 371 >Chapter 4</A
 372 >.</P
 373 ><DIV
 374 CLASS="SECT2"
 375 ><H2
 376 CLASS="SECT2"
 377 ><A
 378 NAME="LANGUAGE.PROPERTIES.USER">Information-providing Properties</H2
 379 ><P
 380 >Users can only be expected to manipulate configuration options
 381 sensibly if they are given sufficient information about these options.
 382 There are three properties which serve to explain an option in plain
 383 text: the <A
 384 HREF="ref.display.html"
 385 ><SPAN
 386 CLASS="PROPERTY"
 387 >display</SPAN
 388 ></A
 389 > property gives
 390 a textual alias for an option, which is usually more comprehensible
 391 than something like <TT
 392 CLASS="LITERAL"
 393 >CYGPKG_LIBC_TIME_ZONES`</TT
 394 >; the
 395 <A
 396 HREF="ref.description.html"
 397 ><SPAN
 398 CLASS="PROPERTY"
 399 >description</SPAN
 400 ></A
 401 > property gives a
 402 longer description, typically a paragraph or so; the <A
 403 HREF="ref.doc.html"
 404 ><SPAN
 405 CLASS="PROPERTY"
 406 >doc</SPAN
 407 ></A
 408 > property specifies the location of
 409 additional on-line documentation related to a configuration option. In
 410 the context of a graphical tool the <SPAN
 411 CLASS="PROPERTY"
 412 >display</SPAN
 413 > string will be the
 414 primary way for users to identify configuration options; the
 415 <SPAN
 416 CLASS="PROPERTY"
 417 >description</SPAN
 418 > paragraph will be visible whenever the option is
 419 selected; the on-line documentation will only be accessed when the
 420 user explicitly requests it.</P
 421 ><TABLE
 422 BORDER="5"
 423 BGCOLOR="#E0E0F0"
 424 WIDTH="70%"
 425 ><TR
 426 ><TD
 427 ><PRE
 428 CLASS="PROGRAMLISTING"
 429 >cdl_package CYGPKG_UITRON {
 430     display       "uITRON compatibility layer"
 431     doc           ref/ecos-ref.a.html
 432     description   "
 433         eCos supports a uITRON Compatibility Layer, providing
 434         full Level S (Standard) compliance with Version 3.02 of
 435         the uITRON Standard, plus many Level E (Extended) features.
 436         uITRON is the premier Japanese embedded RTOS standard."
 437     &#8230;
 438 }</PRE
 439 ></TD
 440 ></TR
 441 ></TABLE
 442 ><P
 443 >All three properties take a single argument. For <SPAN
 444 CLASS="PROPERTY"
 445 >display</SPAN
 446 > and
 447 <SPAN
 448 CLASS="PROPERTY"
 449 >description</SPAN
 450 > this argument is just a string. For <SPAN
 451 CLASS="PROPERTY"
 452 >doc</SPAN
 453 > it should be a
 454 pointer to a suitable HTML file, optionally including an anchor within
 455 that page. If the <A
 456 HREF="package.html#PACKAGE.HIERARCHY"
 457 >directory layout
 458 conventions</A
 459 > are observed then the component framework will look
 460 for the HTML file in the package's <TT
 461 CLASS="FILENAME"
 462 >doc</TT
 463 > sub-directory, otherwise the <SPAN
 464 CLASS="PROPERTY"
 465 >doc</SPAN
 466 >
 467 filename will be treated as relative to the package's top-level directory.</P
 468 ></DIV
 469 ><DIV
 470 CLASS="SECT2"
 471 ><H2
 472 CLASS="SECT2"
 473 ><A
 474 NAME="LANGUAGE.PROPERTIES.HIERARCHY">The Configuration Hierarchy</H2
 475 ><P
 476 >There are two properties related to the hierarchical organization of
 477 components and options: <A
 478 HREF="ref.parent.html"
 479 ><SPAN
 480 CLASS="PROPERTY"
 481 >parent</SPAN
 482 ></A
 483 > and
 484 <A
 485 HREF="ref.script.html"
 486 ><SPAN
 487 CLASS="PROPERTY"
 488 >script</SPAN
 489 ></A
 490 >.</P
 491 ><P
 492 >The <SPAN
 493 CLASS="PROPERTY"
 494 >parent</SPAN
 495 > property can be used to move a <SPAN
 496 CLASS="APPLICATION"
 497 >CDL</SPAN
 498 > entity somewhere
 499 else in the hierarchy. The most common use is for packages, to avoid
 500 having all the packages appear at the top-level of the configuration
 501 hierarchy. For example an architectural HAL package such as
 502 <TT
 503 CLASS="VARNAME"
 504 >CYGPKG_HAL_SH</TT
 505 > is placed below the common HAL
 506 package <TT
 507 CLASS="VARNAME"
 508 >CYGPKG_HAL</TT
 509 > using a <SPAN
 510 CLASS="PROPERTY"
 511 >parent</SPAN
 512 > property.</P
 513 ><TABLE
 514 BORDER="5"
 515 BGCOLOR="#E0E0F0"
 516 WIDTH="70%"
 517 ><TR
 518 ><TD
 519 ><PRE
 520 CLASS="PROGRAMLISTING"
 521 >cdl_package CYGPKG_HAL_SH {
 522     display       "SH architecture"
 523     parent        CYGPKG_HAL
 524     &#8230;
 525 }</PRE
 526 ></TD
 527 ></TR
 528 ></TABLE
 529 ><P
 530 >The <SPAN
 531 CLASS="PROPERTY"
 532 >parent</SPAN
 533 > property can also be used in the body of a
 534 <TT
 535 CLASS="LITERAL"
 536 >cdl_component</TT
 537 >, <TT
 538 CLASS="LITERAL"
 539 >cdl_option</TT
 540 > or <TT
 541 CLASS="LITERAL"
 542 >cdl_interface</TT
 543 >, but this is less
 544 common. However care has to be taken since excessive re-parenting can
 545 be confusing. Care also has to be taken when reparenting below some
 546 other package that may not actually be loaded in a given
 547 configuration, since the resulting behavior is undefined.</P
 548 ><P
 549 >As a special case, if the parent is the empty string then the
 550 <SPAN
 551 CLASS="APPLICATION"
 552 >CDL</SPAN
 553 > entity is placed at the root of the hierarchy. This is useful
 554 for global preferences, default compiler flags, and other settings
 555 that may affect every package.</P
 556 ><P
 557 >The <SPAN
 558 CLASS="PROPERTY"
 559 >script</SPAN
 560 > property can only be used in the body of a
 561 <TT
 562 CLASS="LITERAL"
 563 >cdl_component</TT
 564 > command. The property takes a single filename as
 565 argument, and this should be another <SPAN
 566 CLASS="APPLICATION"
 567 >CDL</SPAN
 568 > script containing
 569 additional options, sub-components and interfaces that should go below
 570 the current component in the hierarchy. If the <A
 571 HREF="package.html#PACKAGE.HIERARCHY"
 572 >directory layout conventions</A
 573 > are
 574 observed then the component framework will look for the specified file
 575 relative to the <TT
 576 CLASS="FILENAME"
 577 >cdl</TT
 578 >
 579 subdirectory of the package, otherwise the filename will be treated as
 580 relative to the package's top-level directory.</P
 581 ><TABLE
 582 BORDER="5"
 583 BGCOLOR="#E0E0F0"
 584 WIDTH="70%"
 585 ><TR
 586 ><TD
 587 ><PRE
 588 CLASS="PROGRAMLISTING"
 589 >cdl_component CYGPKG_LIBC_STDIO {
 590     display       "Standard input/output functions"
 591     flavor        bool
 592     requires      CYGPKG_IO
 593     requires      CYGPKG_IO_SERIAL_HALDIAG
 594     default_value 1
 595     description   "
 596         This enables support for standard I/O functions from &lt;stdio.h&gt;."
 597
 598     script        stdio.cdl
 599 }</PRE
 600 ></TD
 601 ></TR
 602 ></TABLE
 603 ></DIV
 604 ><DIV
 605 CLASS="SECT2"
 606 ><H2
 607 CLASS="SECT2"
 608 ><A
 609 NAME="LANGUAGE.PROPERTIES.VALUE">Value-related Properties</H2
 610 ><P
 611 >There are seven properties which are related to option values and
 612 state: <A
 613 HREF="ref.flavor.html"
 614 ><SPAN
 615 CLASS="PROPERTY"
 616 >flavor</SPAN
 617 ></A
 618 >,
 619 <A
 620 HREF="ref.calculated.html"
 621 ><SPAN
 622 CLASS="PROPERTY"
 623 >calculated</SPAN
 624 ></A
 625 >,
 626 <A
 627 HREF="ref.default-value.html"
 628 ><SPAN
 629 CLASS="PROPERTY"
 630 >default_value</SPAN
 631 ></A
 632 >,
 633 <A
 634 HREF="ref.legal-values.html"
 635 ><SPAN
 636 CLASS="PROPERTY"
 637 >legal_values</SPAN
 638 ></A
 639 >,
 640 <A
 641 HREF="ref.active-if.html"
 642 ><SPAN
 643 CLASS="PROPERTY"
 644 >active_if</SPAN
 645 ></A
 646 >,
 647 <A
 648 HREF="ref.implements.html"
 649 ><SPAN
 650 CLASS="PROPERTY"
 651 >implements</SPAN
 652 ></A
 653 >, and
 654 <A
 655 HREF="ref.requires.html"
 656 ><SPAN
 657 CLASS="PROPERTY"
 658 >requires</SPAN
 659 ></A
 660 >. More detailed
 661 information can be found in <A
 662 HREF="language.values.html"
 663 >the Section called <I
 664 >Values and Expressions</I
 665 ></A
 666 >.</P
 667 ><P
 668 >In the context of configurability, the concept of an option's value is
 669 somewhat non-trivial. First an option may or may not be loaded: it is
 670 possible to build a configuration which has the math library but not
 671 the kernel; however the math library's <SPAN
 672 CLASS="APPLICATION"
 673 >CDL</SPAN
 674 > scripts still reference
 675 kernel options, for example
 676 <TT
 677 CLASS="VARNAME"
 678 >CYGSEM_LIBM_THREAD_SAFE_COMPAT_MODE</TT
 679 > has a
 680 <SPAN
 681 CLASS="PROPERTY"
 682 >requires</SPAN
 683 > constraint on
 684 <TT
 685 CLASS="VARNAME"
 686 >CYGVAR_KERNEL_THREADS_DATA</TT
 687 >. Even if an option is
 688 loaded it may or may not be active, depending on what is happening
 689 higher up in the hierarchy: if the C library's
 690 <TT
 691 CLASS="VARNAME"
 692 >CYGPKG_LIBC_STDIO</TT
 693 > component is disabled then some
 694 other options such as <TT
 695 CLASS="VARNAME"
 696 >CYGNUM_LIBC_STDIO_BUFSIZE</TT
 697 >
 698 become irrelevant. In addition each option has both a boolean
 699 enabled/disabled flag and a data part. For many options only the
 700 boolean flag is of interest, while for others only the data part is of
 701 interest. The <SPAN
 702 CLASS="PROPERTY"
 703 >flavor</SPAN
 704 > property can be used to control this:</P
 705 ><P
 706 ></P
 707 ><DIV
 708 CLASS="VARIABLELIST"
 709 ><DL
 710 ><DT
 711 ><TT
 712 CLASS="LITERAL"
 713 >flavor none</TT
 714 ></DT
 715 ><DD
 716 ><P
 717 >This flavor indicates that neither the boolean nor the data parts are
 718 user-modifiable: the option is always enabled and the data is always
 719 set to <TT
 720 CLASS="LITERAL"
 721 >1</TT
 722 >. The most common use for this is to have a
 723 component that just acts as a placeholder in the hierarchy, allowing
 724 various options to be grouped below it.</P
 725 ></DD
 726 ><DT
 727 ><TT
 728 CLASS="LITERAL"
 729 >flavor bool</TT
 730 ></DT
 731 ><DD
 732 ><P
 733 >Only the boolean part of the option is user-modifiable. The data part
 734 is fixed at <TT
 735 CLASS="LITERAL"
 736 >1</TT
 737 >.</P
 738 ></DD
 739 ><DT
 740 ><TT
 741 CLASS="LITERAL"
 742 >flavor data</TT
 743 ></DT
 744 ><DD
 745 ><P
 746 >Only the data part of the option is user-modifiable. The boolean part
 747 is fixed at enabled.</P
 748 ></DD
 749 ><DT
 750 ><TT
 751 CLASS="LITERAL"
 752 >flavor booldata</TT
 753 ></DT
 754 ><DD
 755 ><P
 756 >Both the boolean and the data part of the option are user-modifiable.</P
 757 ></DD
 758 ></DL
 759 ></DIV
 760 ><P
 761 >For more details of <SPAN
 762 CLASS="APPLICATION"
 763 >CDL</SPAN
 764 > flavors and how a flavor affects expression
 765 evaluation, and other consequences, see <A
 766 HREF="language.values.html"
 767 >the Section called <I
 768 >Values and Expressions</I
 769 ></A
 770 >. The <SPAN
 771 CLASS="PROPERTY"
 772 >flavor</SPAN
 773 > property cannot be used for a
 774 package because packages always have the <TT
 775 CLASS="LITERAL"
 776 >booldata</TT
 777 >
 778 flavor. Options and components have the <TT
 779 CLASS="LITERAL"
 780 >bool</TT
 781 > flavor
 782 by default, since most configuration choices are simple yes-or-no
 783 choices. Interfaces have the <TT
 784 CLASS="LITERAL"
 785 >data</TT
 786 > flavor by default.</P
 787 ><P
 788 >The <SPAN
 789 CLASS="PROPERTY"
 790 >calculated</SPAN
 791 > property can be used for options which should not be
 792 user-modifiable, but which instead are fixed by the target hardware or
 793 determined from the current values of other options. In general
 794 <SPAN
 795 CLASS="PROPERTY"
 796 >calculated</SPAN
 797 > options should be avoided, since they can be confusing to
 798 users who need to figure out whether or not a particular option can
 799 actually be changed. There are a number of valid uses for <SPAN
 800 CLASS="PROPERTY"
 801 >calculated</SPAN
 802 >
 803 options, and quite a few invalid ones as well. The <A
 804 HREF="ref.calculated.html"
 805 >reference packages</A
 806 > should be consulted
 807 for further details. The property takes an <A
 808 HREF="language.values.html#LANGUAGE.EXPRESSION"
 809 >ordinary <SPAN
 810 CLASS="APPLICATION"
 811 >CDL</SPAN
 812 > expression</A
 813 > as
 814 argument, for example:</P
 815 ><TABLE
 816 BORDER="5"
 817 BGCOLOR="#E0E0F0"
 818 WIDTH="70%"
 819 ><TR
 820 ><TD
 821 ><PRE
 822 CLASS="PROGRAMLISTING"
 823 ># A constant on some target hardware, perhaps user-modifiable on other
 824 # targets.
 825 cdl_option CYGNUM_HAL_RTC_PERIOD {
 826     display       "Real-time clock period"
 827     flavor        data
 828     calculated    12500
 829 }</PRE
 830 ></TD
 831 ></TR
 832 ></TABLE
 833 ><P
 834 >The <SPAN
 835 CLASS="PROPERTY"
 836 >calculated</SPAN
 837 > property cannot be used for packages or interfaces.
 838 The value of a package always corresponds to the version of that
 839 package which is loaded, and this is under user control. Interfaces
 840 are implicitly calculated, based on the number of active and enabled
 841 implementors.</P
 842 ><P
 843 >The <SPAN
 844 CLASS="PROPERTY"
 845 >default_value</SPAN
 846 > property is similar to <SPAN
 847 CLASS="PROPERTY"
 848 >calculated</SPAN
 849 >, but only
 850 specifies a default value which users can modify. Again this property
 851 is not relevant to packages or interfaces. A typical example would be:</P
 852 ><TABLE
 853 BORDER="5"
 854 BGCOLOR="#E0E0F0"
 855 WIDTH="70%"
 856 ><TR
 857 ><TD
 858 ><PRE
 859 CLASS="PROGRAMLISTING"
 860 >cdl_option CYGDBG_HAL_DEBUG_GDB_THREAD_SUPPORT {
 861     display       "Include GDB multi-threading debug support"
 862     requires      CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
 863     default_value CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
 864     &#8230;
 865 }</PRE
 866 ></TD
 867 ></TR
 868 ></TABLE
 869 ><P
 870 >The <SPAN
 871 CLASS="PROPERTY"
 872 >legal_values</SPAN
 873 > property imposes a constraint on the possible
 874 values of the data part of an option. Hence it is only applicable to
 875 options with the <TT
 876 CLASS="LITERAL"
 877 >data</TT
 878 > or
 879 <TT
 880 CLASS="LITERAL"
 881 >booldata</TT
 882 > flavors. It cannot be used for a package
 883 since the only valid value for a package is its version number. The
 884 arguments to the <SPAN
 885 CLASS="PROPERTY"
 886 >legal_values</SPAN
 887 > property should constitute a <A
 888 HREF="language.values.html#LANGUAGE.LIST-EXPRESSION"
 889 ><SPAN
 890 CLASS="APPLICATION"
 891 >CDL</SPAN
 892 > list expression</A
 893 >.</P
 894 ><TABLE
 895 BORDER="5"
 896 BGCOLOR="#E0E0F0"
 897 WIDTH="70%"
 898 ><TR
 899 ><TD
 900 ><PRE
 901 CLASS="PROGRAMLISTING"
 902 >cdl_option CYGNUM_LIBC_TIME_STD_DEFAULT_OFFSET {
 903     display       "Default Standard Time offset"
 904     flavor        data
 905     legal_values  -- -90000 to 90000
 906     default_value -- 0
 907     &#8230;
 908 }</PRE
 909 ></TD
 910 ></TR
 911 ></TABLE
 912 ><P
 913 >The <SPAN
 914 CLASS="PROPERTY"
 915 >active_if</SPAN
 916 > property does not relate directly to an option's
 917 value, but rather to its active state. Usually this is controlled via
 918 the configuration hierarchy: if the
 919 <TT
 920 CLASS="VARNAME"
 921 >CYGPKG_LIBC_STDIO</TT
 922 > component is disabled then all
 923 options below it are inactive and do not have any consequences.
 924 In some cases the hierarchy does not provide sufficient control, for
 925 example an option should only be active if two disjoint sets of
 926 conditions are satisfied: the hierarchy could be used for one of these
 927 conditions, and an additional <SPAN
 928 CLASS="PROPERTY"
 929 >active_if</SPAN
 930 > property could be used for
 931 the other one. The arguments to <SPAN
 932 CLASS="PROPERTY"
 933 >active_if</SPAN
 934 > should constitute a
 935 <A
 936 HREF="language.values.html#LANGUAGE.GOAL-EXPRESSION"
 937 ><SPAN
 938 CLASS="APPLICATION"
 939 >CDL</SPAN
 940 > goal expression</A
 941 >.</P
 942 ><TABLE
 943 BORDER="5"
 944 BGCOLOR="#E0E0F0"
 945 WIDTH="70%"
 946 ><TR
 947 ><TD
 948 ><PRE
 949 CLASS="PROGRAMLISTING"
 950 ># Do not provide extra semaphore debugging if there are no semaphores
 951 cdl_option CYGDBG_KERNEL_INSTRUMENT_BINSEM {
 952     active_if CYGPKG_KERNEL_SYNCH
 953     &#8230;
 954 }</PRE
 955 ></TD
 956 ></TR
 957 ></TABLE
 958 ><P
 959 >The <SPAN
 960 CLASS="PROPERTY"
 961 >implements</SPAN
 962 > property is related to the concept of <A
 963 HREF="language.interface.html"
 964 ><SPAN
 965 CLASS="APPLICATION"
 966 >CDL</SPAN
 967 > interfaces</A
 968 >. If an option is
 969 active and enabled and it implements a particular interface then it
 970 contributes <TT
 971 CLASS="LITERAL"
 972 >1</TT
 973 > to that interface's value.</P
 974 ><TABLE
 975 BORDER="5"
 976 BGCOLOR="#E0E0F0"
 977 WIDTH="70%"
 978 ><TR
 979 ><TD
 980 ><PRE
 981 CLASS="PROGRAMLISTING"
 982 >cdl_package CYGPKG_NET_EDB7XXX_ETH_DRIVERS {
 983     display       "Cirrus Logic ethernet driver"
 984     implements    CYGHWR_NET_DRIVERS
 985     implements    CYGHWR_NET_DRIVER_ETH0
 986     &#8230;
 987 }</PRE
 988 ></TD
 989 ></TR
 990 ></TABLE
 991 ><P
 992 >The <SPAN
 993 CLASS="PROPERTY"
 994 >requires</SPAN
 995 > property is used to impose constraints on the user's
 996 choices. For example it is unreasonable to expect the C library to
 997 provide thread-safe implementations of certain functions if the
 998 underlying kernel support has been disabled, or even if the kernel is
 999 not being used at all.</P
1000 ><TABLE
1001 BORDER="5"
1002 BGCOLOR="#E0E0F0"
1003 WIDTH="70%"
1004 ><TR
1005 ><TD
1006 ><PRE
1007 CLASS="PROGRAMLISTING"
1008 >cdl_option CYGSEM_LIBC_PER_THREAD_ERRNO {
1009     display       "Per-thread errno"
1010     doc           ref/ecos-ref.15.html
1011     requires      CYGVAR_KERNEL_THREADS_DATA
1012     default_value 1
1013     &#8230;
1014 }</PRE
1015 ></TD
1016 ></TR
1017 ></TABLE
1018 ><P
1019 >The arguments to the <SPAN
1020 CLASS="PROPERTY"
1021 >requires</SPAN
1022 > property should be a <A
1023 HREF="language.values.html#LANGUAGE.GOAL-EXPRESSION"
1024 ><SPAN
1025 CLASS="APPLICATION"
1026 >CDL</SPAN
1027 > goal expression</A
1028 >.</P
1029 ></DIV
1030 ><DIV
1031 CLASS="SECT2"
1032 ><H2
1033 CLASS="SECT2"
1034 ><A
1035 NAME="LANGUAGE.PROPERTIES.DEFINE">Generating the Configuration Header Files</H2
1036 ><P
1037 >When creating or updating a build tree the component framework will
1038 also generate configuration header files, one per package. By default
1039 it will generate a <TT
1040 CLASS="LITERAL"
1041 >#define</TT
1042 > for each option,
1043 component or interface that is active and enabled. For options with
1044 the <TT
1045 CLASS="LITERAL"
1046 >data</TT
1047 > or <TT
1048 CLASS="LITERAL"
1049 >booldata</TT
1050 > flavors the
1051 <TT
1052 CLASS="LITERAL"
1053 >#define</TT
1054 > will use the option's data part, otherwise
1055 it will use the constant <TT
1056 CLASS="LITERAL"
1057 >1</TT
1058 >. Typical output would
1059 include:</P
1060 ><TABLE
1061 BORDER="5"
1062 BGCOLOR="#E0E0F0"
1063 WIDTH="70%"
1064 ><TR
1065 ><TD
1066 ><PRE
1067 CLASS="PROGRAMLISTING"
1068 >#define CYGFUN_LIBC_TIME_POSIX 1
1069 #define CYGNUM_LIBC_TIME_DST_DEFAULT_STATE -1</PRE
1070 ></TD
1071 ></TR
1072 ></TABLE
1073 ><P
1074 >There are six properties which can be used to control the header file
1075 generation process:
1076 <A
1077 HREF="ref.define-header.html"
1078 ><SPAN
1079 CLASS="PROPERTY"
1080 >define_header</SPAN
1081 ></A
1082 >,
1083 <A
1084 HREF="ref.no-define.html"
1085 ><SPAN
1086 CLASS="PROPERTY"
1087 >no_define</SPAN
1088 ></A
1089 >,
1090 <A
1091 HREF="ref.define-format.html"
1092 ><SPAN
1093 CLASS="PROPERTY"
1094 >define_format</SPAN
1095 ></A
1096 >,
1097 <A
1098 HREF="ref.define.html"
1099 ><SPAN
1100 CLASS="PROPERTY"
1101 >define</SPAN
1102 ></A
1103 >,
1104 <A
1105 HREF="ref.if-define.html"
1106 ><SPAN
1107 CLASS="PROPERTY"
1108 >if_define</SPAN
1109 ></A
1110 >, and
1111 <A
1112 HREF="ref.define-proc.html"
1113 ><SPAN
1114 CLASS="PROPERTY"
1115 >define_proc</SPAN
1116 ></A
1117 >.</P
1118 ><P
1119 >By default the component framework will generate a configuration
1120 header file for each package based on the package's name: everything
1121 up to and including the first underscore is discarded, the rest of the
1122 name is lower-cased, and a <TT
1123 CLASS="LITERAL"
1124 >.h</TT
1125 > suffix is appended.
1126 For example the configuration header file for the kernel package
1127 <TT
1128 CLASS="VARNAME"
1129 >CYGPKG_KERNEL</TT
1130 > is <TT
1131 CLASS="FILENAME"
1132 >pkgconf/kernel.h</TT
1133 >. The <SPAN
1134 CLASS="PROPERTY"
1135 >define_header</SPAN
1136 >
1137 property can be used to specify an alternative filename. This applies
1138 to all the components and options within a package, so it can only be
1139 used in the body of a <TT
1140 CLASS="LITERAL"
1141 >cdl_package</TT
1142 > command. For example the following
1143 specifies that the configuration header file for the SPARClite HAL
1144 package is <TT
1145 CLASS="FILENAME"
1146 >pkgconf/hal_sparclite.h</TT
1147 >.</P
1148 ><TABLE
1149 BORDER="5"
1150 BGCOLOR="#E0E0F0"
1151 WIDTH="70%"
1152 ><TR
1153 ><TD
1154 ><PRE
1155 CLASS="PROGRAMLISTING"
1156 >cdl_package CYGPKG_HAL_SPARCLITE {
1157     display "SPARClite architecture"
1158     parent        CYGPKG_HAL
1159     hardware
1160     define_header hal_sparclite.h
1161     &#8230;
1162 }</PRE
1163 ></TD
1164 ></TR
1165 ></TABLE
1166 ><DIV
1167 CLASS="NOTE"
1168 ><BLOCKQUOTE
1169 CLASS="NOTE"
1170 ><P
1171 ><B
1172 >Note: </B
1173 >At present the main use for the <SPAN
1174 CLASS="PROPERTY"
1175 >define_header</SPAN
1176 > property is related
1177 to hardware packages, see the <A
1178 HREF="ref.hardware.html"
1179 >reference
1180 pages</A
1181 > for more details.</P
1182 ></BLOCKQUOTE
1183 ></DIV
1184 ><P
1185 >The <SPAN
1186 CLASS="PROPERTY"
1187 >no_define</SPAN
1188 > property is used to suppress the generation of the
1189 default <TT
1190 CLASS="LITERAL"
1191 >#define</TT
1192 >. This can be useful if an option's
1193 consequences are all related to the build process or to constraints,
1194 and the option is never actually checked in any source code. It can
1195 also be useful in conjunction with the <SPAN
1196 CLASS="PROPERTY"
1197 >define</SPAN
1198 >, <SPAN
1199 CLASS="PROPERTY"
1200 >if_define</SPAN
1201 > or
1202 <SPAN
1203 CLASS="PROPERTY"
1204 >define_proc</SPAN
1205 > properties. The <SPAN
1206 CLASS="PROPERTY"
1207 >no_define</SPAN
1208 > property does not take any
1209 arguments. </P
1210 ><TABLE
1211 BORDER="5"
1212 BGCOLOR="#E0E0F0"
1213 WIDTH="70%"
1214 ><TR
1215 ><TD
1216 ><PRE
1217 CLASS="PROGRAMLISTING"
1218 >cdl_component CYG_HAL_STARTUP {
1219     display       "Startup type"
1220     flavor        data
1221     legal_values  { "RAM" "ROM" }
1222     default_value {"RAM"}
1223     no_define
1224     define -file system.h CYG_HAL_STARTUP
1225     &#8230;
1226 }</PRE
1227 ></TD
1228 ></TR
1229 ></TABLE
1230 ><P
1231 >This example also illustrates the <SPAN
1232 CLASS="PROPERTY"
1233 >define</SPAN
1234 > property, which can be used
1235 to generate a <TT
1236 CLASS="LITERAL"
1237 >#define</TT
1238 > in addition to the default
1239 one. It takes a single argument, the name of the symbol to be defined.
1240 It also takes options to control the configuration header file in
1241 which the symbol should be defined and the format to be used.</P
1242 ><P
1243 >The <SPAN
1244 CLASS="PROPERTY"
1245 >define_format</SPAN
1246 > property can be used to control how the value part
1247 of the default <TT
1248 CLASS="LITERAL"
1249 >#define</TT
1250 > gets formatted. For example
1251 a format string of  <TT
1252 CLASS="LITERAL"
1253 >"0x%04x"</TT
1254 > could be used to
1255 generate a four-digit hexadecimal number. </P
1256 ><P
1257 >The <SPAN
1258 CLASS="PROPERTY"
1259 >if_define</SPAN
1260 > property is intended for use primarily to control
1261 assertions, tracing, and similar functionality. It supports a specific
1262 implementation model for these, allowing control at the grain of
1263 packages or even individual source files. The <A
1264 HREF="ref.if-define.html"
1265 >reference pages</A
1266 > provide additional
1267 information.</P
1268 ><P
1269 >The <SPAN
1270 CLASS="PROPERTY"
1271 >define_proc</SPAN
1272 > property provides an escape mechanism for those
1273 cases where something special has to happen at configuration header
1274 file generation time. It takes a single argument, a fragment of <SPAN
1275 CLASS="APPLICATION"
1276 >Tcl</SPAN
1277 >
1278 code, which gets executed when the header file is generated. This code
1279 can output arbitrary data to the header file, or perform any other
1280 actions that might be appropriate.</P
1281 ></DIV
1282 ><DIV
1283 CLASS="SECT2"
1284 ><H2
1285 CLASS="SECT2"
1286 ><A
1287 NAME="LANGUAGE.PROPERTIES.BUILD">Controlling what gets Built</H2
1288 ><P
1289 >There are six properties which affect the build process:
1290 <A
1291 HREF="ref.compile.html"
1292 ><SPAN
1293 CLASS="PROPERTY"
1294 >compile</SPAN
1295 ></A
1296 >,
1297 <A
1298 HREF="ref.make.html"
1299 ><SPAN
1300 CLASS="PROPERTY"
1301 >make</SPAN
1302 ></A
1303 >,
1304 <A
1305 HREF="ref.make-object.html"
1306 ><SPAN
1307 CLASS="PROPERTY"
1308 >make_object</SPAN
1309 ></A
1310 >,
1311 <A
1312 HREF="ref.library.html"
1313 ><SPAN
1314 CLASS="PROPERTY"
1315 >library</SPAN
1316 ></A
1317 >,
1318 <A
1319 HREF="ref.include-dir.html"
1320 ><SPAN
1321 CLASS="PROPERTY"
1322 >include_dir</SPAN
1323 ></A
1324 >, and
1325 <A
1326 HREF="ref.include-files.html"
1327 ><SPAN
1328 CLASS="PROPERTY"
1329 >include_files</SPAN
1330 ></A
1331 >.
1332 The last three apply to a package as a whole, and can only occur in
1333 the body of a <TT
1334 CLASS="LITERAL"
1335 >cdl_package</TT
1336 > command.</P
1337 ><P
1338 >Most of the source files that go into a package should simply be
1339 compiled with the appropriate compiler, selected by the target
1340 architecture, and with the appropriate flags, with an additional set
1341 defined by the target hardware and possible modifications on a
1342 per-package basis. The resulting object files will go into the library
1343 <TT
1344 CLASS="FILENAME"
1345 >libtarget.a</TT
1346 >, which can then be linked against
1347 application code. The <SPAN
1348 CLASS="PROPERTY"
1349 >compile</SPAN
1350 > property is used to list these source
1351 files: </P
1352 ><TABLE
1353 BORDER="5"
1354 BGCOLOR="#E0E0F0"
1355 WIDTH="70%"
1356 ><TR
1357 ><TD
1358 ><PRE
1359 CLASS="PROGRAMLISTING"
1360 >cdl_package CYGPKG_ERROR {
1361     display       "Common error code support"
1362     compile       strerror.cxx
1363     include_dir   cyg/error
1364     &#8230;
1365 }</PRE
1366 ></TD
1367 ></TR
1368 ></TABLE
1369 ><P
1370 >The arguments to the <SPAN
1371 CLASS="PROPERTY"
1372 >compile</SPAN
1373 > property should be one or more source
1374 files. Typically most of the sources will be needed for the package as
1375 a whole, and hence they will be listed in one or more <SPAN
1376 CLASS="PROPERTY"
1377 >compile</SPAN
1378 >
1379 properties in the body of the <TT
1380 CLASS="LITERAL"
1381 >cdl_package</TT
1382 >. Some sources may be
1383 specific to particular configuration options, in other words there is
1384 no point in compiling them unless that option is enabled, in which
1385 case the sources should be listed in a <SPAN
1386 CLASS="PROPERTY"
1387 >compile</SPAN
1388 > property in the
1389 corresponding <TT
1390 CLASS="LITERAL"
1391 >cdl_option</TT
1392 >, <TT
1393 CLASS="LITERAL"
1394 >cdl_component</TT
1395 > or <TT
1396 CLASS="LITERAL"
1397 >cdl_interface</TT
1398 > body.</P
1399 ><P
1400 >Some packages may have more complicated build requirements, for
1401 example they may involve a special target such as a linker script
1402 which should not end up in the usual library, or they may involve
1403 special build steps for generating an object file. The <SPAN
1404 CLASS="PROPERTY"
1405 >make</SPAN
1406 > and
1407 <SPAN
1408 CLASS="PROPERTY"
1409 >make_object</SPAN
1410 > properties provide support for such requirements, for
1411 example:</P
1412 ><TABLE
1413 BORDER="5"
1414 BGCOLOR="#E0E0F0"
1415 WIDTH="70%"
1416 ><TR
1417 ><TD
1418 ><PRE
1419 CLASS="PROGRAMLISTING"
1420 >cdl_package CYGPKG_HAL_MN10300_AM33 {
1421     display       "MN10300 AM33 variant"
1422     &#8230;
1423     make {
1424         &lt;PREFIX&gt;/lib/target.ld: &lt;PACKAGE&gt;/src/mn10300_am33.ld
1425         $(CC) -E -P -Wp,-MD,target.tmp -DEXTRAS=1 -xc $(INCLUDE_PATH) \
1426             $(CFLAGS) -o $@ $&lt;
1427         @echo $@ ": \\" &gt; $(notdir $@).deps
1428         @tail +2 target.tmp &gt;&gt; $(notdir $@).deps
1429         @echo &gt;&gt; $(notdir $@).deps
1430         @rm target.tmp
1431     }
1432 }</PRE
1433 ></TD
1434 ></TR
1435 ></TABLE
1436 ><P
1437 >For full details of custom build steps and the build process
1438 generally, see <A
1439 HREF="build.html"
1440 >Chapter 4</A
1441 >.</P
1442 ><P
1443 >By default all object files go into the library
1444 <TT
1445 CLASS="FILENAME"
1446 >libtarget.a</TT
1447 >. It is possible to override this at
1448 the package level using the <SPAN
1449 CLASS="PROPERTY"
1450 >library</SPAN
1451 > property, but this should be
1452 avoided since it complicates application development: instead of just
1453 linking with a single library for all <SPAN
1454 CLASS="APPLICATION"
1455 >eCos</SPAN
1456 >-related packages, it
1457 suddenly becomes necessary to link with several libraries.</P
1458 ><P
1459 >The <SPAN
1460 CLASS="PROPERTY"
1461 >include_dir</SPAN
1462 > and <SPAN
1463 CLASS="PROPERTY"
1464 >include_files</SPAN
1465 > properties relate to a package's
1466 exported header files. By default a package's header files will be
1467 exported to the <TT
1468 CLASS="FILENAME"
1469 >install/include</TT
1470 >
1471 directory. This is the desired behavior for some packages like the C
1472 library, since headers like <TT
1473 CLASS="FILENAME"
1474 >stdio.h</TT
1475 > should exist at that level.
1476 However if all header files were to end up in that directory then
1477 there would be a significant risk of a name clash. Instead it is
1478 better for packages to specify some sub-directory for their exported
1479 header files, for example:</P
1480 ><TABLE
1481 BORDER="5"
1482 BGCOLOR="#E0E0F0"
1483 WIDTH="70%"
1484 ><TR
1485 ><TD
1486 ><PRE
1487 CLASS="PROGRAMLISTING"
1488 >cdl_package CYGPKG_INFRA {
1489     display       "Infrastructure"
1490     include_dir   cyg/infra
1491     &#8230;
1492 }</PRE
1493 ></TD
1494 ></TR
1495 ></TABLE
1496 ><P
1497 >The various header files exported by the infrastructure, for example
1498 <TT
1499 CLASS="FILENAME"
1500 >cyg_ass.h</TT
1501 > and <TT
1502 CLASS="FILENAME"
1503 >cyg_trac.h</TT
1504 > will now end up in the
1505 <TT
1506 CLASS="FILENAME"
1507 >install/include/cyg/infra</TT
1508 >
1509 sub-directory, where a name clash is very unlikely.</P
1510 ><P
1511 >For packages which follow the <A
1512 HREF="package.html#PACKAGE.HIERARCHY"
1513 >directory layout conventions</A
1514 > the
1515 component framework will assume that the package's
1516 <TT
1517 CLASS="FILENAME"
1518 >include</TT
1519 > sub-directory contains
1520 all exported header files. If this is not the case, for example
1521 because the package is sufficiently simple that the layout convention
1522 is inappropriate, then the exported header files can be listed
1523 explicitly in an <SPAN
1524 CLASS="PROPERTY"
1525 >include_files</SPAN
1526 > property.</P
1527 ></DIV
1528 ><DIV
1529 CLASS="SECT2"
1530 ><H2
1531 CLASS="SECT2"
1532 ><A
1533 NAME="LANGUAGE.PROPERTIES.MISCELLANEOUS">Miscellaneous Properties</H2
1534 ><P
1535 >The <A
1536 HREF="ref.hardware.html"
1537 ><SPAN
1538 CLASS="PROPERTY"
1539 >hardware</SPAN
1540 ></A
1541 > property is
1542 only relevant to packages. Some packages such as device drivers and
1543 HAL packages are hardware-specific, and generally it makes no sense to
1544 add such packages to a configuration unless the corresponding hardware
1545 is present on your target system. Typically hardware package selection
1546 happens automatically when you select your target. The <SPAN
1547 CLASS="PROPERTY"
1548 >hardware</SPAN
1549 >
1550 property should be used to identify a hardware-specific package, and
1551 does not take any arguments.</P
1552 ><TABLE
1553 BORDER="5"
1554 BGCOLOR="#E0E0F0"
1555 WIDTH="70%"
1556 ><TR
1557 ><TD
1558 ><PRE
1559 CLASS="PROGRAMLISTING"
1560 >cdl_package CYGPKG_HAL_MIPS {
1561     display "MIPS architecture"
1562     parent        CYGPKG_HAL
1563     hardware
1564     include_dir   cyg/hal
1565     define_header hal_mips.h
1566     &#8230;
1567 }</PRE
1568 ></TD
1569 ></TR
1570 ></TABLE
1571 ><P
1572 >At present the <SPAN
1573 CLASS="PROPERTY"
1574 >hardware</SPAN
1575 > property is largely ignored by the component
1576 framework. This may change in future releases.</P
1577 ></DIV
1578 ></DIV
1579 ><DIV
1580 CLASS="NAVFOOTER"
1581 ><HR
1582 ALIGN="LEFT"
1583 WIDTH="100%"><TABLE
1584 SUMMARY="Footer navigation table"
1585 WIDTH="100%"
1586 BORDER="0"
1587 CELLPADDING="0"
1588 CELLSPACING="0"
1589 ><TR
1590 ><TD
1591 WIDTH="33%"
1592 ALIGN="left"
1593 VALIGN="top"
1594 ><A
1595 HREF="language.commands.html"
1596 ACCESSKEY="P"
1597 >Prev</A
1598 ></TD
1599 ><TD
1600 WIDTH="34%"
1601 ALIGN="center"
1602 VALIGN="top"
1603 ><A
1604 HREF="cdl-guide.html"
1605 ACCESSKEY="H"
1606 >Home</A
1607 ></TD
1608 ><TD
1609 WIDTH="33%"
1610 ALIGN="right"
1611 VALIGN="top"
1612 ><A
1613 HREF="language.naming.html"
1614 ACCESSKEY="N"
1615 >Next</A
1616 ></TD
1617 ></TR
1618 ><TR
1619 ><TD
1620 WIDTH="33%"
1621 ALIGN="left"
1622 VALIGN="top"
1623 >CDL Commands</TD
1624 ><TD
1625 WIDTH="34%"
1626 ALIGN="center"
1627 VALIGN="top"
1628 ><A
1629 HREF="language.html"
1630 ACCESSKEY="U"
1631 >Up</A
1632 ></TD
1633 ><TD
1634 WIDTH="33%"
1635 ALIGN="right"
1636 VALIGN="top"
1637 >Option Naming Convention</TD
1638 ></TR
1639 ></TABLE
1640 ></DIV
1641 ></BODY
1642 ></HTML
1643 >