doc/html/cdl-guide/language.commands.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 Commands</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="The CDL Language"
  26 HREF="language.html"><LINK
  27 REL="NEXT"
  28 TITLE="CDL Properties"
  29 HREF="language.properties.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.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.properties.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.COMMANDS">CDL Commands</H1
  89 ><P
  90 >There are four <SPAN
  91 CLASS="APPLICATION"
  92 >CDL</SPAN
  93 >-related commands which can occur at the top-level
  94 of a <SPAN
  95 CLASS="APPLICATION"
  96 >CDL</SPAN
  97 > script: <TT
  98 CLASS="LITERAL"
  99 >cdl_package</TT
 100 >, <TT
 101 CLASS="LITERAL"
 102 >cdl_component</TT
 103 >, <TT
 104 CLASS="LITERAL"
 105 >cdl_option</TT
 106 > and
 107 <TT
 108 CLASS="LITERAL"
 109 >cdl_interface</TT
 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
 114 >Interfaces</I
 115 ></A
 116 >). All of these take the same basic form:</P
 117 ><TABLE
 118 BORDER="5"
 119 BGCOLOR="#E0E0F0"
 120 WIDTH="70%"
 121 ><TR
 122 ><TD
 123 ><PRE
 124 CLASS="PROGRAMLISTING"
 125 >cdl_package &lt;name&gt; {
 126     &#8230;
 127 }
 128
 129 cdl_component &lt;name&gt; {
 130     &#8230;
 131 }
 132
 133 cdl_option &lt;name&gt; {
 134     &#8230;
 135 }
 136
 137 cdl_interface &lt;name&gt; {
 138     &#8230;
 139 }</PRE
 140 ></TD
 141 ></TR
 142 ></TABLE
 143 ><P
 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
 146 entities, so the <TT
 147 CLASS="LITERAL"
 148 >cdl_package</TT
 149 > and <TT
 150 CLASS="LITERAL"
 151 >cdl_component</TT
 152 > can also have
 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
 157 <A
 158 HREF="language.naming.html"
 159 >naming convention</A
 160 > which should
 161 make accidental name clashes very unlikely.</P
 162 ><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
 166 given <SPAN
 167 CLASS="APPLICATION"
 168 >eCos</SPAN
 169 > configuration can be used on only one processor, so the
 170 architectural HAL packages <TT
 171 CLASS="VARNAME"
 172 >CYGPKG_HAL_ARM</TT
 173 > and
 174 <TT
 175 CLASS="VARNAME"
 176 >CYGPKG_HAL_I386</TT
 177 > can re-use option names; in fact
 178 in some cases they are expected to.</P
 179 ><P
 180 >Each package has one top-level <SPAN
 181 CLASS="APPLICATION"
 182 >CDL</SPAN
 183 > script, which is specified in the
 184 packages <A
 185 HREF="language.database.html"
 186 ><SPAN
 187 CLASS="DATABASE"
 188 >ecos.db</SPAN
 189 > database
 190 entry</A
 191 >. Typically the name of this top-level script is related to
 192 the package, so the kernel package uses
 193 <TT
 194 CLASS="FILENAME"
 195 >kernel.cdl</TT
 196 >, but this is just a convention. The
 197 first command in the top-level script should be <TT
 198 CLASS="LITERAL"
 199 >cdl_package</TT
 200 >, and the
 201 name used should be the same as in the <SPAN
 202 CLASS="DATABASE"
 203 >ecos.db</SPAN
 204 >
 205 database. There should be only one <TT
 206 CLASS="LITERAL"
 207 >cdl_package</TT
 208 > command per package.</P
 209 ><P
 210 >The various <SPAN
 211 CLASS="APPLICATION"
 212 >CDL</SPAN
 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
 222 ><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
 228 ><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
 231 CLASS="PROPERTY"
 232 >parent</SPAN
 233 > property. For example
 234 an architectural HAL package such as <TT
 235 CLASS="VARNAME"
 236 >CYGPKG_HAL_SH</TT
 237 >
 238 typically re-parents itself below <TT
 239 CLASS="VARNAME"
 240 >CYGPKG_HAL</TT
 241 >, and a
 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
 246 ><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
 250 CLASS="LITERAL"
 251 >cdl_package</TT
 252 >
 253 command. The following two script fragments are equivalent:</P
 254 ><TABLE
 255 BORDER="5"
 256 BGCOLOR="#E0E0F0"
 257 WIDTH="70%"
 258 ><TR
 259 ><TD
 260 ><PRE
 261 CLASS="PROGRAMLISTING"
 262 >cdl_package CYGPKG_LIBC {
 263     &#8230;
 264 }
 265
 266 cdl_component CYGPKG_LIBC_STRING {
 267     &#8230;
 268 }
 269
 270 cdl_option CYGPKG_LIBC_CTYPE_INLINES {
 271     &#8230;
 272 }</PRE
 273 ></TD
 274 ></TR
 275 ></TABLE
 276 ><P
 277 >and:</P
 278 ><TABLE
 279 BORDER="5"
 280 BGCOLOR="#E0E0F0"
 281 WIDTH="70%"
 282 ><TR
 283 ><TD
 284 ><PRE
 285 CLASS="PROGRAMLISTING"
 286 >cdl_package CYGPKG_LIBC {
 287     &#8230;
 288
 289     cdl_component CYGPKG_LIBC_STRING {
 290         &#8230;
 291     }
 292
 293     cdl_option CYGPKG_LIBC_CTYPE_INLINES {
 294         &#8230;
 295     }
 296 }</PRE
 297 ></TD
 298 ></TR
 299 ></TABLE
 300 ><P
 301 >If a script defines options both inside and outside the body of the
 302 <TT
 303 CLASS="LITERAL"
 304 >cdl_package</TT
 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
 310 ><P
 311 >Components can also contain options and other <SPAN
 312 CLASS="APPLICATION"
 313 >CDL</SPAN
 314 > entities, in fact
 315 that is what distinguishes them from options. These can be defined in
 316 the body of the <TT
 317 CLASS="LITERAL"
 318 >cdl_component</TT
 319 > command:</P
 320 ><TABLE
 321 BORDER="5"
 322 BGCOLOR="#E0E0F0"
 323 WIDTH="70%"
 324 ><TR
 325 ><TD
 326 ><PRE
 327 CLASS="PROGRAMLISTING"
 328 >cdl_component CYGPKG_LIBC_STDIO {
 329
 330     cdl_component CYGPKG_LIBC_STDIO_FLOATING_POINT {
 331         &#8230;
 332     }
 333
 334     cdl_option CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS {
 335         &#8230;
 336     }
 337 }</PRE
 338 ></TD
 339 ></TR
 340 ></TABLE
 341 ><P
 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
 346 CLASS="APPLICATION"
 347 >CDL</SPAN
 348 > data into multiple <SPAN
 349 CLASS="APPLICATION"
 350 >CDL</SPAN
 351 >
 352 scripts, on a per-component basis. The <SPAN
 353 CLASS="PROPERTY"
 354 >script</SPAN
 355 > property should be
 356 used for this. For example, in the case of the C library all
 357 stdio-related configuration options could be put into
 358 <TT
 359 CLASS="FILENAME"
 360 >stdio.cdl</TT
 361 >, and the top-level CDL script
 362 <TT
 363 CLASS="FILENAME"
 364 >libc.cdl</TT
 365 > would contain the following:</P
 366 ><TABLE
 367 BORDER="5"
 368 BGCOLOR="#E0E0F0"
 369 WIDTH="70%"
 370 ><TR
 371 ><TD
 372 ><PRE
 373 CLASS="PROGRAMLISTING"
 374 >cdl_package CYGPKG_LIBC {
 375     &#8230;
 376
 377     cdl_component CYGPKG_LIBC_STDIO {
 378         &#8230;
 379         script stdio.cdl
 380     }
 381 }</PRE
 382 ></TD
 383 ></TR
 384 ></TABLE
 385 ><P
 386 >The <TT
 387 CLASS="VARNAME"
 388 >CYGPKG_LIBC_STDIO_FLOATING_POINT</TT
 389 > component and
 390 the <TT
 391 CLASS="VARNAME"
 392 >CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS</TT
 393 > option
 394 can then be placed at the top-level of <TT
 395 CLASS="FILENAME"
 396 >stdio.cdl</TT
 397 >.
 398 It is possible to have some options nested in the body of a
 399 <TT
 400 CLASS="LITERAL"
 401 >cdl_component</TT
 402 > command and other options in a separate file accessed
 403 by the <SPAN
 404 CLASS="PROPERTY"
 405 >script</SPAN
 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
 408 specified by a <SPAN
 409 CLASS="PROPERTY"
 410 >script</SPAN
 411 > property should only define new options,
 412 components or interfaces: it should not contain any additional
 413 properties for the current component.</P
 414 ><P
 415 >It is possible for a component's <SPAN
 416 CLASS="APPLICATION"
 417 >CDL</SPAN
 418 > script to have a sub-component
 419 which also has a <SPAN
 420 CLASS="PROPERTY"
 421 >script</SPAN
 422 > property, and so on. In practice excessive
 423 nesting like this is rarely useful. It is also possible to ignore the
 424 <SPAN
 425 CLASS="APPLICATION"
 426 >CDL</SPAN
 427 > language support for constructing hierarchies automatically and
 428 use the <SPAN
 429 CLASS="PROPERTY"
 430 >parent</SPAN
 431 > property explicitly for every single option and
 432 component. Again this is not generally useful.</P
 433 ><DIV
 434 CLASS="NOTE"
 435 ><BLOCKQUOTE
 436 CLASS="NOTE"
 437 ><P
 438 ><B
 439 >Note: </B
 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
 443 CLASS="PROPERTY"
 444 >script</SPAN
 445 > property, just like
 446 components.</P
 447 ></BLOCKQUOTE
 448 ></DIV
 449 ></DIV
 450 ><DIV
 451 CLASS="NAVFOOTER"
 452 ><HR
 453 ALIGN="LEFT"
 454 WIDTH="100%"><TABLE
 455 SUMMARY="Footer navigation table"
 456 WIDTH="100%"
 457 BORDER="0"
 458 CELLPADDING="0"
 459 CELLSPACING="0"
 460 ><TR
 461 ><TD
 462 WIDTH="33%"
 463 ALIGN="left"
 464 VALIGN="top"
 465 ><A
 466 HREF="language.html"
 467 ACCESSKEY="P"
 468 >Prev</A
 469 ></TD
 470 ><TD
 471 WIDTH="34%"
 472 ALIGN="center"
 473 VALIGN="top"
 474 ><A
 475 HREF="cdl-guide.html"
 476 ACCESSKEY="H"
 477 >Home</A
 478 ></TD
 479 ><TD
 480 WIDTH="33%"
 481 ALIGN="right"
 482 VALIGN="top"
 483 ><A
 484 HREF="language.properties.html"
 485 ACCESSKEY="N"
 486 >Next</A
 487 ></TD
 488 ></TR
 489 ><TR
 490 ><TD
 491 WIDTH="33%"
 492 ALIGN="left"
 493 VALIGN="top"
 494 >The CDL Language</TD
 495 ><TD
 496 WIDTH="34%"
 497 ALIGN="center"
 498 VALIGN="top"
 499 ><A
 500 HREF="language.html"
 501 ACCESSKEY="U"
 502 >Up</A
 503 ></TD
 504 ><TD
 505 WIDTH="33%"
 506 ALIGN="right"
 507 VALIGN="top"
 508 >CDL Properties</TD
 509 ></TR
 510 ></TABLE
 511 ></DIV
 512 ></BODY
 513 ></HTML
 514 >