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. -->
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="The eCos Component Writer's Guide"
20 HREF="cdl-guide.html"><LINK
22 TITLE="The CDL Language"
23 HREF="language.html"><LINK
25 TITLE="The CDL Language"
26 HREF="language.html"><LINK
28 TITLE="CDL Properties"
29 HREF="language.properties.html"></HEAD
40 SUMMARY="Header navigation table"
52 > Component Writer's Guide</TH
68 >Chapter 3. The CDL Language</TD
74 HREF="language.properties.html"
88 NAME="LANGUAGE.COMMANDS">CDL Commands</H1
93 >-related commands which can occur at the top-level
110 >. These correspond to the basic building blocks of the
111 language (CDL interfaces are described in <A
112 HREF="language.interface.html"
113 >the Section called <I
116 >). All of these take the same basic form:</P
124 CLASS="PROGRAMLISTING"
125 >cdl_package <name> {
129 cdl_component <name> {
133 cdl_option <name> {
137 cdl_interface <name> {
144 >The command is followed by a name and by a body of properties, the
145 latter enclosed in braces. Packages and components can contain other
153 nested commands in their bodies. All names must be unique within a
154 given configuration. If say the C library package and a TCP/IP stack
155 both defined an option with the same name then it would not be
156 possible to load both of them into a single configuration. There is a
158 HREF="language.naming.html"
159 >naming convention</A
161 make accidental name clashes very unlikely.</P
163 >It is possible for two packages to use the same name if there are no
164 reasonable circumstances under which both packages could be loaded at
165 the same time. One example would be architectural HAL packages: a
169 > configuration can be used on only one processor, so the
170 architectural HAL packages <TT
177 > can re-use option names; in fact
178 in some cases they are expected to.</P
180 >Each package has one top-level <SPAN
183 > script, which is specified in the
185 HREF="language.database.html"
191 >. Typically the name of this top-level script is related to
192 the package, so the kernel package uses
196 >, but this is just a convention. The
197 first command in the top-level script should be <TT
201 name used should be the same as in the <SPAN
205 database. There should be only one <TT
208 > command per package.</P
213 > entities live in a hierarchy. For example the kernel
214 package contains a scheduling component, a synchronization primitives
215 component, and a number of others. The synchronization component
216 contains various options such as whether or not mutex priority
217 inheritance is enabled. There is no upper bound on how far components
218 can be nested, but it is rarely necessary to go more than three or
219 four levels deeper than the package level. Since the naming convention
220 incorporates bits of the hierarchy, this has the added advantage of
221 keeping the names down to a more manageable size.</P
223 >The hierarchy serves two purposes. It allows options to be controlled
224 en masse, so disabling a component automatically disables all the
225 options below it in the hierarchy. It also permits a much simpler
226 representation of the configuration in the graphical configuration
227 tool, facilitating navigation and modification.</P
229 >By default a package is placed at the top-level of the hierarchy, but
230 it is possible to override this using a <SPAN
233 > property. For example
234 an architectural HAL package such as <TT
238 typically re-parents itself below <TT
242 platform HAL package would then re-parent itself below the
243 architectural HAL. This makes it a little bit easier for users to
244 navigate around the hierarchy. Components, options and interfaces can
245 also be re-parented, but this is less common.</P
247 >All components, options and interfaces that are defined directly in
248 the top-level script will be placed below the package in the hierarchy.
249 Alternatively they can be nested in the body of the <TT
253 command. The following two script fragments are equivalent:</P
261 CLASS="PROGRAMLISTING"
262 >cdl_package CYGPKG_LIBC {
266 cdl_component CYGPKG_LIBC_STRING {
270 cdl_option CYGPKG_LIBC_CTYPE_INLINES {
285 CLASS="PROGRAMLISTING"
286 >cdl_package CYGPKG_LIBC {
289 cdl_component CYGPKG_LIBC_STRING {
293 cdl_option CYGPKG_LIBC_CTYPE_INLINES {
301 >If a script defines options both inside and outside the body of the
305 > then the ones inside will be processed first. Language
306 purists may argue that it would have been better if all contained
307 options and components had to go into the body, but in practice it is
308 often convenient to be able to skip this level of nesting and the
309 resulting behavior is still well-defined.</P
311 >Components can also contain options and other <SPAN
315 that is what distinguishes them from options. These can be defined in
327 CLASS="PROGRAMLISTING"
328 >cdl_component CYGPKG_LIBC_STDIO {
330 cdl_component CYGPKG_LIBC_STDIO_FLOATING_POINT {
334 cdl_option CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS {
342 >Nesting options inside the bodies of components like this is fine for
343 simple packages with only a limited number of configuration options,
344 but it becomes unsatisfactory as the number of options increases.
345 Instead it is possible to split the <SPAN
348 > data into multiple <SPAN
352 scripts, on a per-component basis. The <SPAN
356 used for this. For example, in the case of the C library all
357 stdio-related configuration options could be put into
361 >, and the top-level CDL script
365 > would contain the following:</P
373 CLASS="PROGRAMLISTING"
374 >cdl_package CYGPKG_LIBC {
377 cdl_component CYGPKG_LIBC_STDIO {
388 >CYGPKG_LIBC_STDIO_FLOATING_POINT</TT
392 >CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS</TT
394 can then be placed at the top-level of <TT
398 It is possible to have some options nested in the body of a
402 > command and other options in a separate file accessed
406 > property. In such a case the nested options would be
407 processed first, and then the other script would be read in. A script
411 > property should only define new options,
412 components or interfaces: it should not contain any additional
413 properties for the current component.</P
415 >It is possible for a component's <SPAN
418 > script to have a sub-component
419 which also has a <SPAN
422 > property, and so on. In practice excessive
423 nesting like this is rarely useful. It is also possible to ignore the
427 > language support for constructing hierarchies automatically and
431 > property explicitly for every single option and
432 component. Again this is not generally useful.</P
440 >At the time of writing interfaces cannot act as containers. This may
441 change in a future version of the component framework. If the change
442 is made then interfaces would support the <SPAN
445 > property, just like
455 SUMMARY="Footer navigation table"
475 HREF="cdl-guide.html"
484 HREF="language.properties.html"
494 >The CDL Language</TD