doc/html/cdl-guide/cdl-guide.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 >The eCos Component Writer's Guide</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="NEXT"
  19 TITLE="Overview"
  20 HREF="overview.html"></HEAD
  21 ><BODY
  22 CLASS="BOOK"
  23 BGCOLOR="#FFFFFF"
  24 TEXT="#000000"
  25 LINK="#0000FF"
  26 VLINK="#840084"
  27 ALINK="#0000FF"
  28 ><DIV
  29 CLASS="BOOK"
  30 ><A
  31 NAME="CDL-GUIDE"><DIV
  32 CLASS="TITLEPAGE"
  33 ><H1
  34 CLASS="TITLE"
  35 ><A
  36 NAME="AEN4">The <SPAN
  37 CLASS="APPLICATION"
  38 >eCos</SPAN
  39 > Component Writer's Guide</H1
  40 ><H3
  41 CLASS="AUTHOR"
  42 ><A
  43 NAME="AEN8">Bart Veer</H3
  44 ><H3
  45 CLASS="AUTHOR"
  46 ><A
  47 NAME="AEN11">John Dallaway</H3
  48 ><P
  49 CLASS="COPYRIGHT"
  50 >Copyright &copy; 2000, 2001 by Red Hat Inc.</P
  51 ><HR></DIV
  52 ><DIV
  53 CLASS="TOC"
  54 ><DL
  55 ><DT
  56 ><B
  57 >Table of Contents</B
  58 ></DT
  59 ><DT
  60 >1. <A
  61 HREF="overview.html"
  62 >Overview</A
  63 ></DT
  64 ><DD
  65 ><DL
  66 ><DT
  67 ><A
  68 HREF="overview.html#OVERVIEW.TERMINOLOGY"
  69 >Terminology</A
  70 ></DT
  71 ><DD
  72 ><DL
  73 ><DT
  74 ><A
  75 HREF="overview.html#CONCEPTS.TERMINOLOGY.FRAMEWORK"
  76 >Component Framework</A
  77 ></DT
  78 ><DT
  79 ><A
  80 HREF="overview.html#CONCEPTS.TERMINOLOGY.OPTION"
  81 >Configuration Option</A
  82 ></DT
  83 ><DT
  84 ><A
  85 HREF="overview.html#CONCEPTS.TERMINOLOGY.COMPONENT"
  86 >Component</A
  87 ></DT
  88 ><DT
  89 ><A
  90 HREF="overview.html#CONCEPTS.TERMINOLOGY.PACKAGE"
  91 >Package</A
  92 ></DT
  93 ><DT
  94 ><A
  95 HREF="overview.html#CONCEPTS.TERMINOLOGY.CONFIGURATION"
  96 >Configuration</A
  97 ></DT
  98 ><DT
  99 ><A
 100 HREF="overview.html#CONCEPTS.TERMINOLOGY.TARGET"
 101 >Target</A
 102 ></DT
 103 ><DT
 104 ><A
 105 HREF="overview.html#CONCEPTS.TERMINOLOGY.TEMPLATE"
 106 >Template</A
 107 ></DT
 108 ><DT
 109 ><A
 110 HREF="overview.html#CONCEPTS.TERMINOLOGY.PROPERTIES"
 111 >Properties</A
 112 ></DT
 113 ><DT
 114 ><A
 115 HREF="overview.html#CONCEPTS.TERMINOLOGY.CONSEQUENCES"
 116 >Consequences</A
 117 ></DT
 118 ><DT
 119 ><A
 120 HREF="overview.html#CONCEPTS.TERMINOLOGY.CONSTRAINTS"
 121 >Constraints</A
 122 ></DT
 123 ><DT
 124 ><A
 125 HREF="overview.html#CONCEPTS.TERMINOLOGY.CONFLICTS"
 126 >Conflicts</A
 127 ></DT
 128 ><DT
 129 ><A
 130 HREF="overview.html#CONCEPTS.TERMINOLOGY.CDL"
 131 >CDL</A
 132 ></DT
 133 ><DT
 134 ><A
 135 HREF="overview.html#CONCEPTS.TERMINOLOGY.REPO"
 136 >Component Repository</A
 137 ></DT
 138 ></DL
 139 ></DD
 140 ><DT
 141 ><A
 142 HREF="overview.configurability.html"
 143 >Why Configurability?</A
 144 ></DT
 145 ><DT
 146 ><A
 147 HREF="overview.approaches.html"
 148 >Approaches to Configurability</A
 149 ></DT
 150 ><DT
 151 ><A
 152 HREF="overview.degress.html"
 153 >Degrees of Configurability</A
 154 ></DT
 155 ><DT
 156 ><A
 157 HREF="overview.warning.html"
 158 >Warnings</A
 159 ></DT
 160 ></DL
 161 ></DD
 162 ><DT
 163 >2. <A
 164 HREF="package.html"
 165 >Package Organization</A
 166 ></DT
 167 ><DD
 168 ><DL
 169 ><DT
 170 ><A
 171 HREF="package.html#PACKAGE.HIERARCHY"
 172 >Packages and the Component Repository</A
 173 ></DT
 174 ><DT
 175 ><A
 176 HREF="package.versions.html"
 177 >Package Versioning</A
 178 ></DT
 179 ><DT
 180 ><A
 181 HREF="package.contents.html"
 182 >Package Contents and Layout</A
 183 ></DT
 184 ><DD
 185 ><DL
 186 ><DT
 187 ><A
 188 HREF="package.contents.html#PACKAGE.BUILD"
 189 >Outline of the Build Process</A
 190 ></DT
 191 ><DT
 192 ><A
 193 HREF="package.contents.html#PACKAGE.SOURCE"
 194 >Configurable Source Code</A
 195 ></DT
 196 ><DT
 197 ><A
 198 HREF="package.contents.html#PACKAGE.HEADERS"
 199 >Exported Header Files</A
 200 ></DT
 201 ><DT
 202 ><A
 203 HREF="package.contents.html#PACKAGE.DOCUMENTATION"
 204 >Package Documentation</A
 205 ></DT
 206 ><DT
 207 ><A
 208 HREF="package.contents.html#PACKAGE.TESTS"
 209 >Test Cases</A
 210 ></DT
 211 ><DT
 212 ><A
 213 HREF="package.contents.html#PACKAGE.HOST"
 214 >Host-side Support</A
 215 ></DT
 216 ></DL
 217 ></DD
 218 ><DT
 219 ><A
 220 HREF="package.distrib.html"
 221 >Making a Package Distribution</A
 222 ></DT
 223 ><DD
 224 ><DL
 225 ><DT
 226 ><A
 227 HREF="package.distrib.html#PACKAGE.DISTRIB.FORMAT"
 228 >The <SPAN
 229 CLASS="APPLICATION"
 230 >eCos</SPAN
 231 > package distribution file format</A
 232 ></DT
 233 ><DT
 234 ><A
 235 HREF="package.distrib.html#PACKAGE.DISTRIB.PREPARE"
 236 >Preparing eCos packages for distribution</A
 237 ></DT
 238 ></DL
 239 ></DD
 240 ></DL
 241 ></DD
 242 ><DT
 243 >3. <A
 244 HREF="language.html"
 245 >The CDL Language</A
 246 ></DT
 247 ><DD
 248 ><DL
 249 ><DT
 250 ><A
 251 HREF="language.html#LANGUAGE.OVERVIEW"
 252 >Language Overview</A
 253 ></DT
 254 ><DT
 255 ><A
 256 HREF="language.commands.html"
 257 >CDL Commands</A
 258 ></DT
 259 ><DT
 260 ><A
 261 HREF="language.properties.html"
 262 >CDL Properties</A
 263 ></DT
 264 ><DD
 265 ><DL
 266 ><DT
 267 ><A
 268 HREF="language.properties.html#LANGUAGE.PROPERTIES.USER"
 269 >Information-providing Properties</A
 270 ></DT
 271 ><DT
 272 ><A
 273 HREF="language.properties.html#LANGUAGE.PROPERTIES.HIERARCHY"
 274 >The Configuration Hierarchy</A
 275 ></DT
 276 ><DT
 277 ><A
 278 HREF="language.properties.html#LANGUAGE.PROPERTIES.VALUE"
 279 >Value-related Properties</A
 280 ></DT
 281 ><DT
 282 ><A
 283 HREF="language.properties.html#LANGUAGE.PROPERTIES.DEFINE"
 284 >Generating the Configuration Header Files</A
 285 ></DT
 286 ><DT
 287 ><A
 288 HREF="language.properties.html#LANGUAGE.PROPERTIES.BUILD"
 289 >Controlling what gets Built</A
 290 ></DT
 291 ><DT
 292 ><A
 293 HREF="language.properties.html#LANGUAGE.PROPERTIES.MISCELLANEOUS"
 294 >Miscellaneous Properties</A
 295 ></DT
 296 ></DL
 297 ></DD
 298 ><DT
 299 ><A
 300 HREF="language.naming.html"
 301 >Option Naming Convention</A
 302 ></DT
 303 ><DT
 304 ><A
 305 HREF="language.tcl.html"
 306 >An Introduction to Tcl</A
 307 ></DT
 308 ><DT
 309 ><A
 310 HREF="language.values.html"
 311 >Values and Expressions</A
 312 ></DT
 313 ><DD
 314 ><DL
 315 ><DT
 316 ><A
 317 HREF="language.values.html#LANGUAGE.VALUES.VALUE"
 318 >Option Values</A
 319 ></DT
 320 ><DT
 321 ><A
 322 HREF="language.values.html#LANGUAGE.EXPRESSION"
 323 >Ordinary Expressions</A
 324 ></DT
 325 ><DT
 326 ><A
 327 HREF="language.values.html#LANGUAGE.FUNCTIONS"
 328 >Functions</A
 329 ></DT
 330 ><DT
 331 ><A
 332 HREF="language.values.html#LANGUAGE.GOAL-EXPRESSION"
 333 >Goal Expressions</A
 334 ></DT
 335 ><DT
 336 ><A
 337 HREF="language.values.html#LANGUAGE.LIST-EXPRESSION"
 338 >List Expressions</A
 339 ></DT
 340 ></DL
 341 ></DD
 342 ><DT
 343 ><A
 344 HREF="language.interface.html"
 345 >Interfaces</A
 346 ></DT
 347 ><DT
 348 ><A
 349 HREF="language.database.html"
 350 >Updating the <SPAN
 351 CLASS="DATABASE"
 352 >ecos.db</SPAN
 353 > database</A
 354 ></DT
 355 ></DL
 356 ></DD
 357 ><DT
 358 >4. <A
 359 HREF="build.html"
 360 >The Build Process</A
 361 ></DT
 362 ><DD
 363 ><DL
 364 ><DT
 365 ><A
 366 HREF="build.html#BUILD.OUTLINE"
 367 >Build Tree Generation</A
 368 ></DT
 369 ><DT
 370 ><A
 371 HREF="build.headers.html"
 372 >Configuration Header File Generation</A
 373 ></DT
 374 ><DD
 375 ><DL
 376 ><DT
 377 ><A
 378 HREF="build.headers.html#BUILD.HEADERS.SYSTEM.H"
 379 >The <TT
 380 CLASS="FILENAME"
 381 >system.h</TT
 382 > Header</A
 383 ></DT
 384 ></DL
 385 ></DD
 386 ><DT
 387 ><A
 388 HREF="build.make.html"
 389 >Building eCos</A
 390 ></DT
 391 ><DD
 392 ><DL
 393 ><DT
 394 ><A
 395 HREF="build.make.html#BUILD.MAKE.UPDATE"
 396 >Updating the Build Tree</A
 397 ></DT
 398 ><DT
 399 ><A
 400 HREF="build.make.html#BUILD.MAKE.EXPORT"
 401 >Exporting Public Header Files</A
 402 ></DT
 403 ><DT
 404 ><A
 405 HREF="build.make.html#BUILD.MAKE.COMPILES"
 406 >Compiling</A
 407 ></DT
 408 ><DT
 409 ><A
 410 HREF="build.make.html#BUILD.MAKE.LIBRARIES"
 411 >Generating the Libraries</A
 412 ></DT
 413 ><DT
 414 ><A
 415 HREF="build.make.html#BUILD.EXTRAS"
 416 >The <TT
 417 CLASS="FILENAME"
 418 >extras.o</TT
 419 > file</A
 420 ></DT
 421 ><DT
 422 ><A
 423 HREF="build.make.html#BUILD.FLAGS"
 424 >Compilers and Flags</A
 425 ></DT
 426 ><DT
 427 ><A
 428 HREF="build.make.html#BUILD.CUSTOM"
 429 >Custom Build Steps</A
 430 ></DT
 431 ><DT
 432 ><A
 433 HREF="build.make.html#BUILD.STARTUP"
 434 >Startup Code</A
 435 ></DT
 436 ><DT
 437 ><A
 438 HREF="build.make.html#BUILD.LINKERSCRIPT"
 439 >The Linker Script</A
 440 ></DT
 441 ></DL
 442 ></DD
 443 ><DT
 444 ><A
 445 HREF="build.tests.html"
 446 >Building Test Cases</A
 447 ></DT
 448 ></DL
 449 ></DD
 450 ><DT
 451 >5. <A
 452 HREF="reference.html"
 453 >CDL Language Specification</A
 454 ></DT
 455 ><DD
 456 ><DL
 457 ><DT
 458 ><A
 459 HREF="ref.cdl-option.html"
 460 ><TT
 461 CLASS="LITERAL"
 462 >cdl_option</TT
 463 ></A
 464 >&nbsp;--&nbsp;Define a single configuration option</DT
 465 ><DT
 466 ><A
 467 HREF="ref.cdl-component.html"
 468 ><TT
 469 CLASS="LITERAL"
 470 >cdl_component</TT
 471 ></A
 472 >&nbsp;--&nbsp;Define a component, a collection of configuration options</DT
 473 ><DT
 474 ><A
 475 HREF="ref.cdl-package.html"
 476 ><TT
 477 CLASS="LITERAL"
 478 >cdl_package</TT
 479 ></A
 480 >&nbsp;--&nbsp;Define a package, a component that can be distributed</DT
 481 ><DT
 482 ><A
 483 HREF="ref.cdl-interface.html"
 484 ><TT
 485 CLASS="LITERAL"
 486 >cdl_interface</TT
 487 ></A
 488 >&nbsp;--&nbsp;Define an interface, functionality that can be provided by
 489 a number of different implementations.</DT
 490 ><DT
 491 ><A
 492 HREF="ref.active-if.html"
 493 ><SPAN
 494 CLASS="PROPERTY"
 495 >active_if</SPAN
 496 ></A
 497 >&nbsp;--&nbsp;Allow additional control over the active state of an
 498 option or other CDL entity.</DT
 499 ><DT
 500 ><A
 501 HREF="ref.calculated.html"
 502 ><SPAN
 503 CLASS="PROPERTY"
 504 >calculated</SPAN
 505 ></A
 506 >&nbsp;--&nbsp;Used if the current option's value is not user-modifiable,
 507 but is calculated using a suitable CDL expression.</DT
 508 ><DT
 509 ><A
 510 HREF="ref.compile.html"
 511 ><SPAN
 512 CLASS="PROPERTY"
 513 >compile</SPAN
 514 ></A
 515 >&nbsp;--&nbsp;List the source files that should be built if this option
 516 is active and enabled.</DT
 517 ><DT
 518 ><A
 519 HREF="ref.default-value.html"
 520 ><SPAN
 521 CLASS="PROPERTY"
 522 >default_value</SPAN
 523 ></A
 524 >&nbsp;--&nbsp;Provide a default value for this option using a CDL expression.</DT
 525 ><DT
 526 ><A
 527 HREF="ref.define.html"
 528 ><SPAN
 529 CLASS="PROPERTY"
 530 >define</SPAN
 531 ></A
 532 >&nbsp;--&nbsp;Specify additional <TT
 533 CLASS="LITERAL"
 534 >#define</TT
 535 > symbols that
 536 should go into the owning package's configuration header file.</DT
 537 ><DT
 538 ><A
 539 HREF="ref.define-format.html"
 540 ><SPAN
 541 CLASS="PROPERTY"
 542 >define_format</SPAN
 543 ></A
 544 >&nbsp;--&nbsp;Control how an option's value will appear in the
 545 configuration header file.</DT
 546 ><DT
 547 ><A
 548 HREF="ref.define-header.html"
 549 ><SPAN
 550 CLASS="PROPERTY"
 551 >define_header</SPAN
 552 ></A
 553 >&nbsp;--&nbsp;Specify the  configuration header file that
 554 will be generated for a given package.</DT
 555 ><DT
 556 ><A
 557 HREF="ref.define-proc.html"
 558 ><SPAN
 559 CLASS="PROPERTY"
 560 >define_proc</SPAN
 561 ></A
 562 >&nbsp;--&nbsp;Use a fragment of Tcl code to output additional data to
 563 configuration header files.</DT
 564 ><DT
 565 ><A
 566 HREF="ref.description.html"
 567 ><SPAN
 568 CLASS="PROPERTY"
 569 >description</SPAN
 570 ></A
 571 >&nbsp;--&nbsp;Provide a textual description for an option.</DT
 572 ><DT
 573 ><A
 574 HREF="ref.display.html"
 575 ><SPAN
 576 CLASS="PROPERTY"
 577 >display</SPAN
 578 ></A
 579 >&nbsp;--&nbsp;Provide a short string describing this option.</DT
 580 ><DT
 581 ><A
 582 HREF="ref.doc.html"
 583 ><SPAN
 584 CLASS="PROPERTY"
 585 >doc</SPAN
 586 ></A
 587 >&nbsp;--&nbsp;The location of online-documentation for a configuration option.</DT
 588 ><DT
 589 ><A
 590 HREF="ref.flavor.html"
 591 ><SPAN
 592 CLASS="PROPERTY"
 593 >flavor</SPAN
 594 ></A
 595 >&nbsp;--&nbsp;Specify the nature of a configuration option.</DT
 596 ><DT
 597 ><A
 598 HREF="ref.hardware.html"
 599 ><SPAN
 600 CLASS="PROPERTY"
 601 >hardware</SPAN
 602 ></A
 603 >&nbsp;--&nbsp;Specify that a package is tied to specific hardware.</DT
 604 ><DT
 605 ><A
 606 HREF="ref.if-define.html"
 607 ><SPAN
 608 CLASS="PROPERTY"
 609 >if_define</SPAN
 610 ></A
 611 >&nbsp;--&nbsp;Output a common preprocessor construct to a configuration
 612 header file.</DT
 613 ><DT
 614 ><A
 615 HREF="ref.implements.html"
 616 ><SPAN
 617 CLASS="PROPERTY"
 618 >implements</SPAN
 619 ></A
 620 >&nbsp;--&nbsp;Enabling this option provides one instance of a more
 621 general interface.</DT
 622 ><DT
 623 ><A
 624 HREF="ref.include-dir.html"
 625 ><SPAN
 626 CLASS="PROPERTY"
 627 >include_dir</SPAN
 628 ></A
 629 >&nbsp;--&nbsp;Specify the desired location of a package's exported
 630 header files in the install tree.</DT
 631 ><DT
 632 ><A
 633 HREF="ref.include-files.html"
 634 ><SPAN
 635 CLASS="PROPERTY"
 636 >include_files</SPAN
 637 ></A
 638 >&nbsp;--&nbsp;List the header files that are exported by a package.</DT
 639 ><DT
 640 ><A
 641 HREF="ref.legal-values.html"
 642 ><SPAN
 643 CLASS="PROPERTY"
 644 >legal_values</SPAN
 645 ></A
 646 >&nbsp;--&nbsp;Impose constraints on the possible values for an option.</DT
 647 ><DT
 648 ><A
 649 HREF="ref.library.html"
 650 ><SPAN
 651 CLASS="PROPERTY"
 652 >library</SPAN
 653 ></A
 654 >&nbsp;--&nbsp;Specify which library should contain the object files
 655 generated by building this package.</DT
 656 ><DT
 657 ><A
 658 HREF="ref.make.html"
 659 ><SPAN
 660 CLASS="PROPERTY"
 661 >make</SPAN
 662 ></A
 663 >&nbsp;--&nbsp;Define an additional custom build step associated with an
 664 option, resulting in a target that should not go directly into a library.</DT
 665 ><DT
 666 ><A
 667 HREF="ref.make-object.html"
 668 ><SPAN
 669 CLASS="PROPERTY"
 670 >make_object</SPAN
 671 ></A
 672 >&nbsp;--&nbsp;Define a custom build step, resulting in an object file
 673 that should go into a library.</DT
 674 ><DT
 675 ><A
 676 HREF="ref.no-define.html"
 677 ><SPAN
 678 CLASS="PROPERTY"
 679 >no_define</SPAN
 680 ></A
 681 >&nbsp;--&nbsp;Suppress the normal generation of a preprocessor
 682 <TT
 683 CLASS="LITERAL"
 684 >#define</TT
 685 > symbol in a configuration header file.</DT
 686 ><DT
 687 ><A
 688 HREF="ref.parent.html"
 689 ><SPAN
 690 CLASS="PROPERTY"
 691 >parent</SPAN
 692 ></A
 693 >&nbsp;--&nbsp;Control the location of an option in the configuration hierarchy.</DT
 694 ><DT
 695 ><A
 696 HREF="ref.requires.html"
 697 ><SPAN
 698 CLASS="PROPERTY"
 699 >requires</SPAN
 700 ></A
 701 >&nbsp;--&nbsp;List constraints that the configuration should satisfy if
 702 a given option is active and enabled..</DT
 703 ><DT
 704 ><A
 705 HREF="ref.script.html"
 706 ><SPAN
 707 CLASS="PROPERTY"
 708 >script</SPAN
 709 ></A
 710 >&nbsp;--&nbsp;Include additional configuration information from another
 711 CDL script.</DT
 712 ></DL
 713 ></DD
 714 ><DT
 715 >6. <A
 716 HREF="advanced.html"
 717 >Templates, Targets and Other Topics</A
 718 ></DT
 719 ><DD
 720 ><DL
 721 ><DT
 722 ><A
 723 HREF="advanced.html#ADVANCED.TEMPLATES"
 724 >Templates</A
 725 ></DT
 726 ><DT
 727 ><A
 728 HREF="advanced.targets.html"
 729 >Targets</A
 730 ></DT
 731 ></DL
 732 ></DD
 733 ></DL
 734 ></DIV
 735 ></DIV
 736 ><DIV
 737 CLASS="NAVFOOTER"
 738 ><HR
 739 ALIGN="LEFT"
 740 WIDTH="100%"><TABLE
 741 SUMMARY="Footer navigation table"
 742 WIDTH="100%"
 743 BORDER="0"
 744 CELLPADDING="0"
 745 CELLSPACING="0"
 746 ><TR
 747 ><TD
 748 WIDTH="33%"
 749 ALIGN="left"
 750 VALIGN="top"
 751 >&nbsp;</TD
 752 ><TD
 753 WIDTH="34%"
 754 ALIGN="center"
 755 VALIGN="top"
 756 >&nbsp;</TD
 757 ><TD
 758 WIDTH="33%"
 759 ALIGN="right"
 760 VALIGN="top"
 761 ><A
 762 HREF="overview.html"
 763 ACCESSKEY="N"
 764 >Next</A
 765 ></TD
 766 ></TR
 767 ><TR
 768 ><TD
 769 WIDTH="33%"
 770 ALIGN="left"
 771 VALIGN="top"
 772 >&nbsp;</TD
 773 ><TD
 774 WIDTH="34%"
 775 ALIGN="center"
 776 VALIGN="top"
 777 >&nbsp;</TD
 778 ><TD
 779 WIDTH="33%"
 780 ALIGN="right"
 781 VALIGN="top"
 782 >Overview</TD
 783 ></TR
 784 ></TABLE
 785 ></DIV
 786 ></BODY
 787 ></HTML
 788 >