OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [language.properties.html] - Blame information for rev 629

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback 
<!-- 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 
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.