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