doc/html/cdl-guide/build.headers.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 >Configuration Header File Generation</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 Build Process"
  23 HREF="build.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="The Build Process"
  26 HREF="build.html"><LINK
  27 REL="NEXT"
  28 TITLE="Building eCos"
  29 HREF="build.make.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="build.html"
  61 ACCESSKEY="P"
  62 >Prev</A
  63 ></TD
  64 ><TD
  65 WIDTH="80%"
  66 ALIGN="center"
  67 VALIGN="bottom"
  68 >Chapter 4. The Build Process</TD
  69 ><TD
  70 WIDTH="10%"
  71 ALIGN="right"
  72 VALIGN="bottom"
  73 ><A
  74 HREF="build.make.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="BUILD.HEADERS">Configuration Header File Generation</H1
  89 ><P
  90 >Configuration options can affect a build in two main ways. First,
  91 enabling a configuration option or other <SPAN
  92 CLASS="APPLICATION"
  93 >CDL</SPAN
  94 > entity can result in
  95 various files being built and added to a library, thus providing
  96 functionality to the application code. However this mechanism can only
  97 operate at a rather coarse grain, at the level of entire source files.
  98 Hence the component framework also generates configuration header
  99 files containing mainly C preprocessor <TT
 100 CLASS="LITERAL"
 101 >#define</TT
 102 >
 103 directives. Package source code can then <TT
 104 CLASS="LITERAL"
 105 >#include</TT
 106 >
 107 the appropriate header files and use <TT
 108 CLASS="LITERAL"
 109 >#if</TT
 110 >,
 111 <TT
 112 CLASS="LITERAL"
 113 >#ifdef</TT
 114 > and <TT
 115 CLASS="LITERAL"
 116 >#ifndef</TT
 117 > directives to
 118 adapt accordingly. In this way configuration options can be used to
 119 enable or disable entire functions within a source file or just a
 120 single line, whichever is appropriate.</P
 121 ><P
 122 >The configuration header files end up in the <TT
 123 CLASS="FILENAME"
 124 >include/pkgconf</TT
 125 > subdirectory of the
 126 install tree. There will be one header file for the system as a whole,
 127 <TT
 128 CLASS="FILENAME"
 129 >pkgconf/system.h</TT
 130 >, and there will
 131 be additional header files for each package, for example
 132 <TT
 133 CLASS="FILENAME"
 134 >pkgconf/kernel.h</TT
 135 >. The header files
 136 are generated when creating or updating the build and install trees,
 137 which needs to happen after every change to the configuration.</P
 138 ><P
 139 >The component framework processes each package in the configuration
 140 one at a time. The exact order in which the packages are processed is
 141 not defined, so the order in which <TT
 142 CLASS="LITERAL"
 143 >#define's</TT
 144 > will
 145 end up in the global <TT
 146 CLASS="FILENAME"
 147 >pkgconf/system.h</TT
 148 > header may vary. However
 149 for any given configuration the order should remain consistent until
 150 packages are added to or removed from the system. This avoids
 151 unnecessary changes to the global header file and hence unnecessary
 152 rebuilds of the packages and of application code because of header
 153 file dependency handling.</P
 154 ><P
 155 >Within a given package the various components, options and interfaces
 156 will be processed in the order in which they were defined in the
 157 corresponding <SPAN
 158 CLASS="APPLICATION"
 159 >CDL</SPAN
 160 > scripts. Typically the data in the configuration
 161 headers consists only of a sequence of <TT
 162 CLASS="LITERAL"
 163 >#define's</TT
 164 > so
 165 the order in which these are generated is irrelevant, but some
 166 properties such as <SPAN
 167 CLASS="PROPERTY"
 168 >define_proc</SPAN
 169 > can be used to add arbitrary data to
 170 a configuration header and hence there may be dependencies on the
 171 order. It should be noted that re-parenting an option below some other
 172 package has no effect on which header file will contain the
 173 corresponding <TT
 174 CLASS="LITERAL"
 175 >#define</TT
 176 >: the preprocessor directives
 177 will always end up in the header file for the package that defines the
 178 option, or in the global configuration header.</P
 179 ><P
 180 >There are six properties which affect the process of generating header
 181 files:
 182 <A
 183 HREF="ref.define-header.html"
 184 ><SPAN
 185 CLASS="PROPERTY"
 186 >define_header</SPAN
 187 ></A
 188 >,
 189 <A
 190 HREF="ref.no-define.html"
 191 ><SPAN
 192 CLASS="PROPERTY"
 193 >no_define</SPAN
 194 ></A
 195 >,
 196 <A
 197 HREF="ref.define-format.html"
 198 ><SPAN
 199 CLASS="PROPERTY"
 200 >define_format</SPAN
 201 ></A
 202 >,
 203 <A
 204 HREF="ref.define.html"
 205 ><SPAN
 206 CLASS="PROPERTY"
 207 >define</SPAN
 208 ></A
 209 >,
 210 <A
 211 HREF="ref.if-define.html"
 212 ><SPAN
 213 CLASS="PROPERTY"
 214 >if_define</SPAN
 215 ></A
 216 >, and
 217 <A
 218 HREF="ref.define-proc.html"
 219 ><SPAN
 220 CLASS="PROPERTY"
 221 >define_proc</SPAN
 222 ></A
 223 >.</P
 224 ><P
 225 >The <SPAN
 226 CLASS="PROPERTY"
 227 >define_header</SPAN
 228 > property can only occur in the body of a
 229 <TT
 230 CLASS="LITERAL"
 231 >cdl_package</TT
 232 > command and specifies the name of the header file which
 233 should contain the package's configuration data, for example:</P
 234 ><TABLE
 235 BORDER="5"
 236 BGCOLOR="#E0E0F0"
 237 WIDTH="70%"
 238 ><TR
 239 ><TD
 240 ><PRE
 241 CLASS="PROGRAMLISTING"
 242 >cdl_package &lt;some_package&gt; {
 243     &#8230;
 244     define_header xyzzy.h
 245 }</PRE
 246 ></TD
 247 ></TR
 248 ></TABLE
 249 ><P
 250 >Given such a <SPAN
 251 CLASS="PROPERTY"
 252 >define_header</SPAN
 253 > property the component framework will
 254 use the file <TT
 255 CLASS="FILENAME"
 256 >pkgconf/xyzzy.h</TT
 257 > for
 258 the package's configuration data. If a package does not have
 259 a <SPAN
 260 CLASS="PROPERTY"
 261 >define_header</SPAN
 262 > property then a suitable file name is constructed
 263 from the package's name. This involves:</P
 264 ><P
 265 ></P
 266 ><OL
 267 TYPE="1"
 268 ><LI
 269 ><P
 270 >All characters in the package name up to and including the first
 271 underscore are removed. For example <TT
 272 CLASS="VARNAME"
 273 >CYGPKG_KERNEL</TT
 274 >
 275 is converted to <TT
 276 CLASS="LITERAL"
 277 >KERNEL</TT
 278 >, and
 279 <TT
 280 CLASS="VARNAME"
 281 >CYGPKG_HAL_ARM</TT
 282 > is converted to
 283 <TT
 284 CLASS="LITERAL"
 285 >HAL_ARM</TT
 286 >.</P
 287 ></LI
 288 ><LI
 289 ><P
 290 >Any upper case letters in the resulting string will be converted to
 291 lower case, yielding e.g. <TT
 292 CLASS="LITERAL"
 293 >kernel</TT
 294 > and
 295 <TT
 296 CLASS="LITERAL"
 297 >hal_arm</TT
 298 >.</P
 299 ></LI
 300 ><LI
 301 ><P
 302 >A <TT
 303 CLASS="LITERAL"
 304 >.h</TT
 305 > suffix is appended, yielding e.g.
 306 <TT
 307 CLASS="LITERAL"
 308 >kernel.h</TT
 309 > and <TT
 310 CLASS="LITERAL"
 311 >hal_arm.h</TT
 312 >.</P
 313 ></LI
 314 ></OL
 315 ><P
 316 >Because of the naming restrictions on configuration options, this
 317 should result in a valid filename. There is a small possibility of a
 318 file name class, for example <TT
 319 CLASS="VARNAME"
 320 >CYGPKG_PLUGH</TT
 321 > and
 322 <TT
 323 CLASS="VARNAME"
 324 >CYGPKG_plugh</TT
 325 > would both end up trying to use the
 326 same header file <TT
 327 CLASS="FILENAME"
 328 >pkgconf/plugh.h</TT
 329 >,
 330 but the use of lower case letters for package names violates the
 331 naming conventions. It is not legal to use the <SPAN
 332 CLASS="PROPERTY"
 333 >define_header</SPAN
 334 >
 335 property to put the configuration data for several packages in a
 336 single header file. The resulting behaviour is undefined.</P
 337 ><P
 338 >Once the name of the package's header file has been determined and the
 339 file has been opened, the various components, options and interfaces
 340 in the package will be processed starting with the package itself. The
 341 following steps are involved:</P
 342 ><P
 343 ></P
 344 ><OL
 345 TYPE="1"
 346 ><LI
 347 ><P
 348 >If the current option or other <SPAN
 349 CLASS="APPLICATION"
 350 >CDL</SPAN
 351 > entity is inactive or disabled,
 352 the option is ignored for the purposes of header file generation.
 353 <TT
 354 CLASS="LITERAL"
 355 >#define's</TT
 356 > are only generated for options that are
 357 both active and enabled.</P
 358 ></LI
 359 ><LI
 360 ><P
 361 >The next step is to generate a default <TT
 362 CLASS="LITERAL"
 363 >#define</TT
 364 > for
 365 the current option. If this option has a <SPAN
 366 CLASS="PROPERTY"
 367 >no_define</SPAN
 368 > property then the
 369 default <TT
 370 CLASS="LITERAL"
 371 >#define</TT
 372 > is suppressed, and processing
 373 continues for <SPAN
 374 CLASS="PROPERTY"
 375 >define</SPAN
 376 >, <SPAN
 377 CLASS="PROPERTY"
 378 >if_define</SPAN
 379 > and <SPAN
 380 CLASS="PROPERTY"
 381 >define_proc</SPAN
 382 > properties.</P
 383 ><P
 384 ></P
 385 ><OL
 386 TYPE="a"
 387 ><LI
 388 ><P
 389 >The header file appropriate for the default <TT
 390 CLASS="LITERAL"
 391 >#define</TT
 392 >
 393 is determined. For a <TT
 394 CLASS="LITERAL"
 395 >cdl_package</TT
 396 > this will be <TT
 397 CLASS="FILENAME"
 398 >pkgconf/system.h</TT
 399 >, for any other option this
 400 will be the package's own header file. The intention here is that
 401 packages and application code can always determine which packages are
 402 in the configuration by <TT
 403 CLASS="LITERAL"
 404 >#include'ing</TT
 405 > <TT
 406 CLASS="FILENAME"
 407 >pkgconf/system.h</TT
 408 >. The C preprocessor lacks
 409 any facilities for including a header file only if it exists, and
 410 taking appropriate action otherwise.</P
 411 ></LI
 412 ><LI
 413 ><P
 414 >For options with the flavors <TT
 415 CLASS="LITERAL"
 416 >bool</TT
 417 > or
 418 <TT
 419 CLASS="LITERAL"
 420 >none</TT
 421 >, a single <TT
 422 CLASS="LITERAL"
 423 >#define</TT
 424 > will be
 425 generated. This takes the form:</P
 426 ><TABLE
 427 BORDER="5"
 428 BGCOLOR="#E0E0F0"
 429 WIDTH="70%"
 430 ><TR
 431 ><TD
 432 ><PRE
 433 CLASS="PROGRAMLISTING"
 434 >#define &lt;option&gt; 1</PRE
 435 ></TD
 436 ></TR
 437 ></TABLE
 438 ><P
 439 >For example:</P
 440 ><TABLE
 441 BORDER="5"
 442 BGCOLOR="#E0E0F0"
 443 WIDTH="70%"
 444 ><TR
 445 ><TD
 446 ><PRE
 447 CLASS="PROGRAMLISTING"
 448 >#define CYGFUN_LIBC_TIME_POSIX 1</PRE
 449 ></TD
 450 ></TR
 451 ></TABLE
 452 ><P
 453 >Package source code can check whether or not an option is active and
 454 enabled by using the <TT
 455 CLASS="LITERAL"
 456 >#ifdef</TT
 457 >,
 458 <TT
 459 CLASS="LITERAL"
 460 >#ifndef</TT
 461 > or <TT
 462 CLASS="LITERAL"
 463 >#if
 464 defined(&#8230;)</TT
 465 >directives.</P
 466 ></LI
 467 ><LI
 468 ><P
 469 >For options with the flavors <TT
 470 CLASS="LITERAL"
 471 >data</TT
 472 > or
 473 <TT
 474 CLASS="LITERAL"
 475 >booldata</TT
 476 >, either one or two
 477 <TT
 478 CLASS="LITERAL"
 479 >#define's</TT
 480 > will be generated. The first of these may
 481 be affected by a <SPAN
 482 CLASS="PROPERTY"
 483 >define_format</SPAN
 484 > property. If this property is not
 485 defined then the first <TT
 486 CLASS="LITERAL"
 487 >#define</TT
 488 > will take the form:</P
 489 ><TABLE
 490 BORDER="5"
 491 BGCOLOR="#E0E0F0"
 492 WIDTH="70%"
 493 ><TR
 494 ><TD
 495 ><PRE
 496 CLASS="PROGRAMLISTING"
 497 >#define &lt;option&gt; &lt;value&gt;</PRE
 498 ></TD
 499 ></TR
 500 ></TABLE
 501 ><P
 502 >For example:</P
 503 ><TABLE
 504 BORDER="5"
 505 BGCOLOR="#E0E0F0"
 506 WIDTH="70%"
 507 ><TR
 508 ><TD
 509 ><PRE
 510 CLASS="PROGRAMLISTING"
 511 >#define CYGNUM_LIBC_ATEXIT_HANDLERS 32</PRE
 512 ></TD
 513 ></TR
 514 ></TABLE
 515 ><P
 516 >Package source code can examine this value using the
 517 <TT
 518 CLASS="LITERAL"
 519 >#if</TT
 520 > directive, or by using the symbol in
 521 code such as:</P
 522 ><TABLE
 523 BORDER="5"
 524 BGCOLOR="#E0E0F0"
 525 WIDTH="70%"
 526 ><TR
 527 ><TD
 528 ><PRE
 529 CLASS="PROGRAMLISTING"
 530 >    for (i = 0; i &#60; CYGNUM_LIBC_ATEXIT_HANDLERS; i++) {
 531         &#8230;
 532     }</PRE
 533 ></TD
 534 ></TR
 535 ></TABLE
 536 ><P
 537 >It must be noted that the <TT
 538 CLASS="LITERAL"
 539 >#define</TT
 540 > will be generated
 541 only if the corresponding option is both active and enabled. Options
 542 with the <TT
 543 CLASS="LITERAL"
 544 >data</TT
 545 > flavor are always enabled but may not
 546 be active. Code like the above should be written only if it is known
 547 that the symbol will always be defined, for example if the
 548 corresponding source file will only get built if the containing
 549 component is active and enabled. Otherwise the use of additional
 550 <TT
 551 CLASS="LITERAL"
 552 >#ifdef</TT
 553 > or similar directives will be necessary.</P
 554 ></LI
 555 ><LI
 556 ><P
 557 >If there is a <SPAN
 558 CLASS="PROPERTY"
 559 >define_format</SPAN
 560 > property then this controls how the
 561 option's value will appear in the header file. Given a format string
 562 such as <TT
 563 CLASS="LITERAL"
 564 >%08x</TT
 565 > and a value 42, the component
 566 framework will execute the <SPAN
 567 CLASS="APPLICATION"
 568 >Tcl</SPAN
 569 > command
 570 <TT
 571 CLASS="LITERAL"
 572 >format&nbsp;%08x&nbsp;42</TT
 573 > and the result will be
 574 used for the <TT
 575 CLASS="LITERAL"
 576 >#define's</TT
 577 > value. It is the
 578 responsibility of the component writer to make sure that this <SPAN
 579 CLASS="APPLICATION"
 580 >Tcl</SPAN
 581 >
 582 command will be valid given the format string and the legal values for
 583 the option.</P
 584 ></LI
 585 ><LI
 586 ><P
 587 >In addition a second <TT
 588 CLASS="LITERAL"
 589 >#define</TT
 590 > may or may not be
 591 generated. This will take the form:</P
 592 ><TABLE
 593 BORDER="5"
 594 BGCOLOR="#E0E0F0"
 595 WIDTH="70%"
 596 ><TR
 597 ><TD
 598 ><PRE
 599 CLASS="PROGRAMLISTING"
 600 >#define &lt;option&gt;_&lt;value&gt;</PRE
 601 ></TD
 602 ></TR
 603 ></TABLE
 604 ><P
 605 >For example:</P
 606 ><TABLE
 607 BORDER="5"
 608 BGCOLOR="#E0E0F0"
 609 WIDTH="70%"
 610 ><TR
 611 ><TD
 612 ><PRE
 613 CLASS="PROGRAMLISTING"
 614 >#define CYGNUM_LIBC_ATEXIT_HANDLERS_32</PRE
 615 ></TD
 616 ></TR
 617 ></TABLE
 618 ><P
 619 >The <TT
 620 CLASS="LITERAL"
 621 >#define</TT
 622 > will be generated only if it would
 623 result in a valid C preprocessor symbol. If the value is a string such
 624 as <TT
 625 CLASS="LITERAL"
 626 >"/dev/ser0"</TT
 627 > then the <TT
 628 CLASS="LITERAL"
 629 >#define</TT
 630 >
 631 would be suppressed. This second <TT
 632 CLASS="LITERAL"
 633 >#define</TT
 634 > is not
 635 particularly useful for numerical data, but can be valuable in other
 636 circumstances. For example if the legal values for an option
 637 <TT
 638 CLASS="LITERAL"
 639 >XXX_COLOR</TT
 640 > are <TT
 641 CLASS="LITERAL"
 642 >red</TT
 643 >,
 644 <TT
 645 CLASS="LITERAL"
 646 >green</TT
 647 > and <TT
 648 CLASS="LITERAL"
 649 >blue</TT
 650 > then code like
 651 the following can be used:</P
 652 ><TABLE
 653 BORDER="5"
 654 BGCOLOR="#E0E0F0"
 655 WIDTH="70%"
 656 ><TR
 657 ><TD
 658 ><PRE
 659 CLASS="PROGRAMLISTING"
 660 >#ifdef XXX_COLOR_red
 661     &#8230;
 662 #endif
 663 #ifdef XXX_COLOR_green
 664     &#8230;
 665 #endif
 666 #ifdef XXX_COLOR_blue
 667     &#8230;
 668 #endif</PRE
 669 ></TD
 670 ></TR
 671 ></TABLE
 672 ><P
 673 >The expression syntax provided by the C preprocessor is limited to
 674 numerical data and cannot perform string comparisons. By generating
 675 two <TT
 676 CLASS="LITERAL"
 677 >#define's</TT
 678 > in this way it is possible to work
 679 around this limitation of the C preprocessor. However some care has to
 680 be taken: if a component writer also defined a configuration option
 681 <TT
 682 CLASS="LITERAL"
 683 >XXX_COLOR_green</TT
 684 > then there will be confusion. Since
 685 such a configuration option violates the naming conventions, the
 686 problem is unlikely to arise in practice.</P
 687 ></LI
 688 ></OL
 689 ></LI
 690 ><LI
 691 ><P
 692 >For some options it may be useful to generate one or more additional
 693 <TT
 694 CLASS="LITERAL"
 695 >#define's</TT
 696 > or, in conjunction with the <SPAN
 697 CLASS="PROPERTY"
 698 >no_define</SPAN
 699 >
 700 property, to define a symbol with a name different from the option's
 701 name. This can be achieved with the <SPAN
 702 CLASS="PROPERTY"
 703 >define</SPAN
 704 > property, which takes the
 705 following form:</P
 706 ><TABLE
 707 BORDER="5"
 708 BGCOLOR="#E0E0F0"
 709 WIDTH="70%"
 710 ><TR
 711 ><TD
 712 ><PRE
 713 CLASS="PROGRAMLISTING"
 714 >    define [-file=&lt;filename&gt;] [-format=&lt;format&gt;] &lt;symbol&gt;</PRE
 715 ></TD
 716 ></TR
 717 ></TABLE
 718 ><P
 719 >For example:</P
 720 ><TABLE
 721 BORDER="5"
 722 BGCOLOR="#E0E0F0"
 723 WIDTH="70%"
 724 ><TR
 725 ><TD
 726 ><PRE
 727 CLASS="PROGRAMLISTING"
 728 >    define FOPEN_MAX</PRE
 729 ></TD
 730 ></TR
 731 ></TABLE
 732 ><P
 733 >This will result in something like:</P
 734 ><TABLE
 735 BORDER="5"
 736 BGCOLOR="#E0E0F0"
 737 WIDTH="70%"
 738 ><TR
 739 ><TD
 740 ><PRE
 741 CLASS="PROGRAMLISTING"
 742 >#define FOPEN_MAX 8
 743 #define FOPEN_MAX_8</PRE
 744 ></TD
 745 ></TR
 746 ></TABLE
 747 ><P
 748 >The specified symbol must be a valid C preprocessor symbol. Normally
 749 the <TT
 750 CLASS="LITERAL"
 751 >#define</TT
 752 > will end up in the same header file as
 753 the default one, in other words <TT
 754 CLASS="FILENAME"
 755 >pkgconf/system.h</TT
 756 > in the case of a
 757 <TT
 758 CLASS="LITERAL"
 759 >cdl_package</TT
 760 >, or the package's own header file for any other option.
 761 The <TT
 762 CLASS="LITERAL"
 763 >-file</TT
 764 > option can be used to change this. At
 765 present the only legal value is <TT
 766 CLASS="LITERAL"
 767 >system.h</TT
 768 >, for
 769 example:</P
 770 ><TABLE
 771 BORDER="5"
 772 BGCOLOR="#E0E0F0"
 773 WIDTH="70%"
 774 ><TR
 775 ><TD
 776 ><PRE
 777 CLASS="PROGRAMLISTING"
 778 >    define -file=system.h &lt;symbol&gt;</PRE
 779 ></TD
 780 ></TR
 781 ></TABLE
 782 ><P
 783 >This will cause the <TT
 784 CLASS="LITERAL"
 785 >#define</TT
 786 > to end up in the global
 787 configuration header rather than in the package's own header. Use of
 788 this facility should be avoided since it is very rarely necessary to
 789 make options globally visible.</P
 790 ><P
 791 >The <SPAN
 792 CLASS="PROPERTY"
 793 >define</SPAN
 794 > property takes another option,
 795 <TT
 796 CLASS="LITERAL"
 797 >-format</TT
 798 >, to provide a format string.</P
 799 ><TABLE
 800 BORDER="5"
 801 BGCOLOR="#E0E0F0"
 802 WIDTH="70%"
 803 ><TR
 804 ><TD
 805 ><PRE
 806 CLASS="PROGRAMLISTING"
 807 >    define -format=%08x &lt;symbol&gt;</PRE
 808 ></TD
 809 ></TR
 810 ></TABLE
 811 ><P
 812 >This should only be used for options with the <TT
 813 CLASS="LITERAL"
 814 >data</TT
 815 >
 816 or <TT
 817 CLASS="LITERAL"
 818 >booldata</TT
 819 > flavor, and has the same effect as the
 820 <SPAN
 821 CLASS="PROPERTY"
 822 >define_format</SPAN
 823 > property has on the default
 824 <TT
 825 CLASS="LITERAL"
 826 >#define</TT
 827 >.</P
 828 ><P
 829 ><SPAN
 830 CLASS="PROPERTY"
 831 >define</SPAN
 832 > properties are processed in the same way the default
 833 <TT
 834 CLASS="LITERAL"
 835 >#define</TT
 836 >. For options with the
 837 <TT
 838 CLASS="LITERAL"
 839 >bool</TT
 840 > or <TT
 841 CLASS="LITERAL"
 842 >none</TT
 843 > flavors a single
 844 <TT
 845 CLASS="LITERAL"
 846 >#define</TT
 847 > will be generated using the value
 848 <TT
 849 CLASS="LITERAL"
 850 >1</TT
 851 >. For options with the <TT
 852 CLASS="LITERAL"
 853 >data</TT
 854 > or
 855 <TT
 856 CLASS="LITERAL"
 857 >booldata</TT
 858 > flavors either one or two
 859 <TT
 860 CLASS="LITERAL"
 861 >#define's</TT
 862 > will be generated.</P
 863 ></LI
 864 ><LI
 865 ><P
 866 >After processing all <SPAN
 867 CLASS="PROPERTY"
 868 >define</SPAN
 869 > properties, the component framework will
 870 look for any <SPAN
 871 CLASS="PROPERTY"
 872 >if_define</SPAN
 873 > properties. These take the following form:</P
 874 ><TABLE
 875 BORDER="5"
 876 BGCOLOR="#E0E0F0"
 877 WIDTH="70%"
 878 ><TR
 879 ><TD
 880 ><PRE
 881 CLASS="PROGRAMLISTING"
 882 >    if_define [-file=&lt;filename&gt;] &lt;symbol1&gt; &lt;symbol2&gt;</PRE
 883 ></TD
 884 ></TR
 885 ></TABLE
 886 ><P
 887 >For example:</P
 888 ><TABLE
 889 BORDER="5"
 890 BGCOLOR="#E0E0F0"
 891 WIDTH="70%"
 892 ><TR
 893 ><TD
 894 ><PRE
 895 CLASS="PROGRAMLISTING"
 896 >    if_define CYGSRC_KERNEL CYGDBG_USE_ASSERTS</PRE
 897 ></TD
 898 ></TR
 899 ></TABLE
 900 ><P
 901 >The following will be generated in the configuration header file:</P
 902 ><TABLE
 903 BORDER="5"
 904 BGCOLOR="#E0E0F0"
 905 WIDTH="70%"
 906 ><TR
 907 ><TD
 908 ><PRE
 909 CLASS="PROGRAMLISTING"
 910 >#ifdef CYGSRC_KERNEL
 911 # define CYGDBG_USE_ASSERTS
 912 #endif</PRE
 913 ></TD
 914 ></TR
 915 ></TABLE
 916 ><P
 917 >Typical kernel source code would begin with the following construct:</P
 918 ><TABLE
 919 BORDER="5"
 920 BGCOLOR="#E0E0F0"
 921 WIDTH="70%"
 922 ><TR
 923 ><TD
 924 ><PRE
 925 CLASS="PROGRAMLISTING"
 926 >#define CYGSRC_KERNEL 1
 927 #include &lt;pkgconf/kernel.h&gt;
 928 #include &lt;cyg/infra/cyg_ass.h&gt;</PRE
 929 ></TD
 930 ></TR
 931 ></TABLE
 932 ><P
 933 >The infrastructure header file <TT
 934 CLASS="FILENAME"
 935 >cyg/infra/cyg_ass.h</TT
 936 > only checks for symbols
 937 such as <TT
 938 CLASS="LITERAL"
 939 >CYGDBG_USE_ASSERTS</TT
 940 >, and has no special
 941 knowledge of the kernel or any other package. The <SPAN
 942 CLASS="PROPERTY"
 943 >if_define</SPAN
 944 > property
 945 will only affect code that defines the symbol
 946 <TT
 947 CLASS="LITERAL"
 948 >CYGSRC_KERNEL</TT
 949 >, so typically only kernel source
 950 code. If the option is enabled then assertion support will be enabled
 951 for the kernel source code only. If the option is inactive or disabled
 952 then kernel assertions will be disabled. Assertions in other packages
 953 are not affected. Thus the <SPAN
 954 CLASS="PROPERTY"
 955 >if_define</SPAN
 956 > property allows control over
 957 assertions, tracing, and similar facilities at the level of individual
 958 packages, or at finer levels such as components or even single source
 959 files if desired.</P
 960 ><DIV
 961 CLASS="NOTE"
 962 ><BLOCKQUOTE
 963 CLASS="NOTE"
 964 ><P
 965 ><B
 966 >Note: </B
 967 >Current <SPAN
 968 CLASS="APPLICATION"
 969 >eCos</SPAN
 970 > packages do not yet make use of this facility. Instead
 971 there is a single global configuration option
 972 <TT
 973 CLASS="VARNAME"
 974 >CYGDBG_USE_ASSERTS</TT
 975 > which is used to enable or
 976 disable assertions for all packages. This issue should be addressed in
 977 a future release of the system.</P
 978 ></BLOCKQUOTE
 979 ></DIV
 980 ><P
 981 >As with the <SPAN
 982 CLASS="PROPERTY"
 983 >define</SPAN
 984 > property, the <SPAN
 985 CLASS="PROPERTY"
 986 >if_define</SPAN
 987 > property takes an
 988 option <TT
 989 CLASS="LITERAL"
 990 >-file</TT
 991 > with a single legal value
 992 <TT
 993 CLASS="LITERAL"
 994 >system.h</TT
 995 >. This allows the output to be redirected
 996 to <TT
 997 CLASS="FILENAME"
 998 >pkgconf/system.h</TT
 999 > if and when
1000 necessary. </P
1001 ></LI
1002 ><LI
1003 ><P
1004 >The final property that is relevant to configuration header file
1005 generation is <SPAN
1006 CLASS="PROPERTY"
1007 >define_proc</SPAN
1008 >. This takes a single argument, a <SPAN
1009 CLASS="APPLICATION"
1010 >Tcl</SPAN
1011 >
1012 fragment that can add arbitrary data to the global header <TT
1013 CLASS="FILENAME"
1014 >pkgconf/system.h</TT
1015 > and to the package's own
1016 header. When the <SPAN
1017 CLASS="PROPERTY"
1018 >define_proc</SPAN
1019 > script is invoked two variables will be
1020 set up to allow access to these headers: <TT
1021 CLASS="LITERAL"
1022 >cdl_header</TT
1023 >
1024 will be a channel to the package's own header file, for example
1025 <TT
1026 CLASS="FILENAME"
1027 >pkgconf/kernel.h</TT
1028 >;
1029 <TT
1030 CLASS="LITERAL"
1031 >cdl_system_header</TT
1032 > will be a channel to <TT
1033 CLASS="FILENAME"
1034 >pkgconf/system.h</TT
1035 >. A typical <SPAN
1036 CLASS="PROPERTY"
1037 >define_proc</SPAN
1038 >
1039 script will use the <SPAN
1040 CLASS="APPLICATION"
1041 >Tcl</SPAN
1042 > <TT
1043 CLASS="LITERAL"
1044 >puts</TT
1045 > command to output
1046 data to one of these channels, for example:</P
1047 ><TABLE
1048 BORDER="5"
1049 BGCOLOR="#E0E0F0"
1050 WIDTH="70%"
1051 ><TR
1052 ><TD
1053 ><PRE
1054 CLASS="PROGRAMLISTING"
1055 >cdl_option &lt;name&gt; {
1056     &#8230;
1057     define_proc {
1058         puts $::cdl_header "#define XXX 1"
1059     }
1060 }</PRE
1061 ></TD
1062 ></TR
1063 ></TABLE
1064 ><DIV
1065 CLASS="NOTE"
1066 ><BLOCKQUOTE
1067 CLASS="NOTE"
1068 ><P
1069 ><B
1070 >Note: </B
1071 >In the current implementation the use of <SPAN
1072 CLASS="PROPERTY"
1073 >define_proc</SPAN
1074 > is limited
1075 because the <SPAN
1076 CLASS="APPLICATION"
1077 >Tcl</SPAN
1078 > script cannot access any of the configuration data.
1079 Therefore the script is limited to writing constant data to the
1080 configuration headers. This is a major limitation which will be
1081 addressed in a future release of the component framework.</P
1082 ></BLOCKQUOTE
1083 ></DIV
1084 ></LI
1085 ></OL
1086 ><DIV
1087 CLASS="NOTE"
1088 ><BLOCKQUOTE
1089 CLASS="NOTE"
1090 ><P
1091 ><B
1092 >Note: </B
1093 >Generating C header files with <TT
1094 CLASS="LITERAL"
1095 >#define's</TT
1096 > for the
1097 configuration data suffices for existing packages written in some
1098 combination of C, C++ and assembler. It can also be used in
1099 conjunction with some other languages, for example by first passing
1100 the source code through the C preprocessor and feeding the result into
1101 the appropriate compiler. In future versions of the component
1102 framework additional programming languages such as Java may be
1103 supported, and the configuration data may also be written to files in
1104 some format other than C preprocessor directives. </P
1105 ></BLOCKQUOTE
1106 ></DIV
1107 ><DIV
1108 CLASS="NOTE"
1109 ><BLOCKQUOTE
1110 CLASS="NOTE"
1111 ><P
1112 ><B
1113 >Note: </B
1114 >At present there is no way for application or package source code to
1115 get hold of all the configuration details related to the current
1116 hardware. Instead that information is spread over various different
1117 configuration headers for the HAL and device driver packages, with
1118 some of the information going into <TT
1119 CLASS="FILENAME"
1120 >pkgconf/system.h</TT
1121 >. It is possible that in
1122 some future release of the system there will be another global
1123 configuration header file <TT
1124 CLASS="FILENAME"
1125 >pkgconf/hardware.h</TT
1126 > which either contains the
1127 configuration details for the various hardware-specific packages or
1128 which <TT
1129 CLASS="LITERAL"
1130 >#include's</TT
1131 > all the hardware-specific
1132 configuration headers. The desirability and feasibility of such a
1133 scheme are still to be determined. To avoid future incompatibility
1134 problems as a result of any such changes, it is recommended that all
1135 hardware packages (in other packages containing the <SPAN
1136 CLASS="PROPERTY"
1137 >hardware</SPAN
1138 >
1139 property) use the <SPAN
1140 CLASS="PROPERTY"
1141 >define_header</SPAN
1142 > property to specify explicitly which
1143 configuration header should be generated.</P
1144 ></BLOCKQUOTE
1145 ></DIV
1146 ><DIV
1147 CLASS="SECT2"
1148 ><H2
1149 CLASS="SECT2"
1150 ><A
1151 NAME="BUILD.HEADERS.SYSTEM.H">The <TT
1152 CLASS="FILENAME"
1153 >system.h</TT
1154 > Header</H2
1155 ><P
1156 >Typically configuration header files are <TT
1157 CLASS="LITERAL"
1158 >#include'd</TT
1159 >
1160 only by the package's source code at build time, or by a package's
1161 exported header files if the interface provided by the package may be
1162 affected by a configuration option. There should be no need for
1163 application code to know the details of individual configuration
1164 options, instead the configuration should specifically meet the needs
1165 of the application.</P
1166 ><P
1167 >There are always exceptions. Application code may want to adapt to
1168 configuration options, for example to do different things for ROM and
1169 RAM booting systems, or when it is necessary to support several
1170 different target boards. This is especially true if the code in question
1171 is really re-usable library code which has not been converted to an
1172 eCos package, and hence cannot use any CDL facilities.</P
1173 ><P
1174 >A major problem here is determining which packages are in the
1175 configuration: attempting to <TT
1176 CLASS="LITERAL"
1177 >#include</TT
1178 > a header file
1179 such as <TT
1180 CLASS="FILENAME"
1181 >pkgconf/net.h</TT
1182 >
1183 when it is not known for certain that that particular package is part
1184 of the configuration will result in compilation errors. The global
1185 header file <TT
1186 CLASS="FILENAME"
1187 >pkgconf/system.h</TT
1188 >
1189 serves to provide such information, so application code can use
1190 techniques like the following:</P
1191 ><TABLE
1192 BORDER="5"
1193 BGCOLOR="#E0E0F0"
1194 WIDTH="70%"
1195 ><TR
1196 ><TD
1197 ><PRE
1198 CLASS="PROGRAMLISTING"
1199 >#include &lt;pkgconf/system.h&gt;
1200 #ifdef CYGPKG_NET
1201 # include &lt;pkgconf/net.h&gt;
1202 #endif</PRE
1203 ></TD
1204 ></TR
1205 ></TABLE
1206 ><P
1207 >This will compile correctly irrespective of the eCos configuration,
1208 and subsequent code can use <TT
1209 CLASS="LITERAL"
1210 >#ifdef</TT
1211 > or similar
1212 directives on <TT
1213 CLASS="LITERAL"
1214 >CYGPKG_NET</TT
1215 > or any of the
1216 configuration options in that package. </P
1217 ><P
1218 >In addition to determining whether or not a package is present, the
1219 global configuration header file can also be used to find out the
1220 specific version of a package that is being used. This can be useful
1221 if a more recent version exports additional functionality. It may also
1222 be necessary to adapt to incompatible changes in the exported
1223 interface or to changes in behaviour. For each package the
1224 configuration system will typically <TT
1225 CLASS="LITERAL"
1226 >#define</TT
1227 > three
1228 symbols, for example for a V1.3.1 release:</P
1229 ><TABLE
1230 BORDER="5"
1231 BGCOLOR="#E0E0F0"
1232 WIDTH="70%"
1233 ><TR
1234 ><TD
1235 ><PRE
1236 CLASS="PROGRAMLISTING"
1237 >#define CYGNUM_NET_VERSION_MAJOR 1
1238 #define CYGNUM_NET_VERSION_MINOR 3
1239 #define CYGNUM_NET_VERSION_RELEASE 1</PRE
1240 ></TD
1241 ></TR
1242 ></TABLE
1243 ><P
1244 >There are a number of problems associated with such version
1245 <TT
1246 CLASS="LITERAL"
1247 >#define's</TT
1248 >. The first restriction is that the
1249 package must follow the standard naming conventions, so the package
1250 name must be of the form <TT
1251 CLASS="LITERAL"
1252 >xxxPKG_yyy</TT
1253 >. The three
1254 characters immediately preceding the first underscore must be
1255 <TT
1256 CLASS="LITERAL"
1257 >PKG</TT
1258 >, and will be replaced with
1259 <TT
1260 CLASS="LITERAL"
1261 >NUM</TT
1262 > when generating the version
1263 <TT
1264 CLASS="LITERAL"
1265 >#define's</TT
1266 >. If a package does not follow the naming
1267 convention then no version <TT
1268 CLASS="LITERAL"
1269 >#define's</TT
1270 > will be
1271 generated. </P
1272 ><P
1273 >Assuming the package does follow the naming conventions, the
1274 configuration tools will always generate three version
1275 <TT
1276 CLASS="LITERAL"
1277 >#define's</TT
1278 > for the major, minor, and release
1279 numbers. The symbol names are obtained from the package name by
1280 replacing <TT
1281 CLASS="LITERAL"
1282 >PKG</TT
1283 > with <TT
1284 CLASS="LITERAL"
1285 >NUM</TT
1286 > and
1287 appending <TT
1288 CLASS="LITERAL"
1289 >_VERSION_MAJOR</TT
1290 >,
1291 <TT
1292 CLASS="LITERAL"
1293 >_VERSION_MINOR</TT
1294 > and
1295 <TT
1296 CLASS="LITERAL"
1297 >_VERSION_RELEASE</TT
1298 >. It is assumed that the resulting
1299 symbols will not clash with any configuration option names. The values
1300 for the <TT
1301 CLASS="LITERAL"
1302 >#define's</TT
1303 > are determined by searching the
1304 version string for sequences of digits, optionally preceded by a minus
1305 sign. It is possible that some or all of the numbers are absent in any
1306 given version string, in which case <TT
1307 CLASS="LITERAL"
1308 >-1</TT
1309 > will be used
1310 in the <TT
1311 CLASS="LITERAL"
1312 >#define</TT
1313 >. For example, given a version string
1314 of <TT
1315 CLASS="LITERAL"
1316 >V1.12beta</TT
1317 >, the major version number is
1318 <TT
1319 CLASS="LITERAL"
1320 >1</TT
1321 >, the minor number is <TT
1322 CLASS="LITERAL"
1323 >12</TT
1324 >, and
1325 the release number is <TT
1326 CLASS="LITERAL"
1327 >-1</TT
1328 >. Given a version string of
1329 <TT
1330 CLASS="LITERAL"
1331 >beta</TT
1332 > all three numbers would be set to
1333 <TT
1334 CLASS="LITERAL"
1335 >-1</TT
1336 >.</P
1337 ><P
1338 >There is special case code for the version <TT
1339 CLASS="LITERAL"
1340 >current</TT
1341 >,
1342 which typically corresponds to a development version obtained via
1343 anonymous CVS or similar means. The configuration system has special
1344 built-in knowledge of this version, and will assume it is more recent
1345 than any specific release number. The global configuration header
1346 defines a special symbol <TT
1347 CLASS="LITERAL"
1348 >CYGNUM_VERSION_CURRENT</TT
1349 >,
1350 and this will be used as the major version number when version
1351 <TT
1352 CLASS="LITERAL"
1353 >current</TT
1354 > of a package is used:</P
1355 ><TABLE
1356 BORDER="5"
1357 BGCOLOR="#E0E0F0"
1358 WIDTH="70%"
1359 ><TR
1360 ><TD
1361 ><PRE
1362 CLASS="PROGRAMLISTING"
1363 >#define CYGNUM_VERSION_CURRENT 0x7fffff00
1364 ...
1365 #define CYGNUM_INFRA_VERSION_MAJOR CYGNUM_VERSION_CURRENT
1366 #define CYGNUM_INFRA_VERSION_MINOR -1
1367 #define CYGNUM_INFRA_VERSION_RELEASE -1</PRE
1368 ></TD
1369 ></TR
1370 ></TABLE
1371 ><P
1372 >The large number used for <TT
1373 CLASS="LITERAL"
1374 >CYGNUM_VERSION_CURRENT</TT
1375 >
1376 should ensure that major version comparisons work as expected, while
1377 still allowing for a small amount of arithmetic in case that proves
1378 useful. </P
1379 ><P
1380 >It should be noted that this implementation of version
1381 <TT
1382 CLASS="LITERAL"
1383 >#define's</TT
1384 > will not cope with all version number
1385 schemes. However for many cases it should suffice.</P
1386 ></DIV
1387 ></DIV
1388 ><DIV
1389 CLASS="NAVFOOTER"
1390 ><HR
1391 ALIGN="LEFT"
1392 WIDTH="100%"><TABLE
1393 SUMMARY="Footer navigation table"
1394 WIDTH="100%"
1395 BORDER="0"
1396 CELLPADDING="0"
1397 CELLSPACING="0"
1398 ><TR
1399 ><TD
1400 WIDTH="33%"
1401 ALIGN="left"
1402 VALIGN="top"
1403 ><A
1404 HREF="build.html"
1405 ACCESSKEY="P"
1406 >Prev</A
1407 ></TD
1408 ><TD
1409 WIDTH="34%"
1410 ALIGN="center"
1411 VALIGN="top"
1412 ><A
1413 HREF="cdl-guide.html"
1414 ACCESSKEY="H"
1415 >Home</A
1416 ></TD
1417 ><TD
1418 WIDTH="33%"
1419 ALIGN="right"
1420 VALIGN="top"
1421 ><A
1422 HREF="build.make.html"
1423 ACCESSKEY="N"
1424 >Next</A
1425 ></TD
1426 ></TR
1427 ><TR
1428 ><TD
1429 WIDTH="33%"
1430 ALIGN="left"
1431 VALIGN="top"
1432 >The Build Process</TD
1433 ><TD
1434 WIDTH="34%"
1435 ALIGN="center"
1436 VALIGN="top"
1437 ><A
1438 HREF="build.html"
1439 ACCESSKEY="U"
1440 >Up</A
1441 ></TD
1442 ><TD
1443 WIDTH="33%"
1444 ALIGN="right"
1445 VALIGN="top"
1446 >Building eCos</TD
1447 ></TR
1448 ></TABLE
1449 ></DIV
1450 ></BODY
1451 ></HTML
1452 >