doc/html/cdl-guide/language.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 CDL Language</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="PREVIOUS"
  22 TITLE="Making a Package Distribution"
  23 HREF="package.distrib.html"><LINK
  24 REL="NEXT"
  25 TITLE="CDL Commands"
  26 HREF="language.commands.html"></HEAD
  27 ><BODY
  28 CLASS="CHAPTER"
  29 BGCOLOR="#FFFFFF"
  30 TEXT="#000000"
  31 LINK="#0000FF"
  32 VLINK="#840084"
  33 ALINK="#0000FF"
  34 ><DIV
  35 CLASS="NAVHEADER"
  36 ><TABLE
  37 SUMMARY="Header navigation table"
  38 WIDTH="100%"
  39 BORDER="0"
  40 CELLPADDING="0"
  41 CELLSPACING="0"
  42 ><TR
  43 ><TH
  44 COLSPAN="3"
  45 ALIGN="center"
  46 >The <SPAN
  47 CLASS="APPLICATION"
  48 >eCos</SPAN
  49 > Component Writer's Guide</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="package.distrib.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="language.commands.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="CHAPTER"
  82 ><H1
  83 ><A
  84 NAME="LANGUAGE">Chapter 3. The CDL Language</H1
  85 ><DIV
  86 CLASS="TOC"
  87 ><DL
  88 ><DT
  89 ><B
  90 >Table of Contents</B
  91 ></DT
  92 ><DT
  93 ><A
  94 HREF="language.html#LANGUAGE.OVERVIEW"
  95 >Language Overview</A
  96 ></DT
  97 ><DT
  98 ><A
  99 HREF="language.commands.html"
 100 >CDL Commands</A
 101 ></DT
 102 ><DT
 103 ><A
 104 HREF="language.properties.html"
 105 >CDL Properties</A
 106 ></DT
 107 ><DT
 108 ><A
 109 HREF="language.naming.html"
 110 >Option Naming Convention</A
 111 ></DT
 112 ><DT
 113 ><A
 114 HREF="language.tcl.html"
 115 >An Introduction to Tcl</A
 116 ></DT
 117 ><DT
 118 ><A
 119 HREF="language.values.html"
 120 >Values and Expressions</A
 121 ></DT
 122 ><DT
 123 ><A
 124 HREF="language.interface.html"
 125 >Interfaces</A
 126 ></DT
 127 ><DT
 128 ><A
 129 HREF="language.database.html"
 130 >Updating the <SPAN
 131 CLASS="DATABASE"
 132 >ecos.db</SPAN
 133 > database</A
 134 ></DT
 135 ></DL
 136 ></DIV
 137 ><P
 138 >The <SPAN
 139 CLASS="APPLICATION"
 140 >CDL</SPAN
 141 > language is a key part of the <SPAN
 142 CLASS="APPLICATION"
 143 >eCos</SPAN
 144 > component framework.
 145 All packages must come with at least one <SPAN
 146 CLASS="APPLICATION"
 147 >CDL</SPAN
 148 > script, to describe
 149 that package to the framework. The information in that script includes
 150 details of all the configuration options and how to build the package.
 151 Implementing a new component or turning some existing code into an
 152 <SPAN
 153 CLASS="APPLICATION"
 154 >eCos</SPAN
 155 > component always involves writing corresponding <SPAN
 156 CLASS="APPLICATION"
 157 >CDL</SPAN
 158 >. This
 159 chapter provides a description of the <SPAN
 160 CLASS="APPLICATION"
 161 >CDL</SPAN
 162 > language. Detailed
 163 information on specific parts of the language can be found in <A
 164 HREF="reference.html"
 165 >Chapter 5</A
 166 >.</P
 167 ><DIV
 168 CLASS="SECT1"
 169 ><H1
 170 CLASS="SECT1"
 171 ><A
 172 NAME="LANGUAGE.OVERVIEW">Language Overview</H1
 173 ><P
 174 >A very simple <SPAN
 175 CLASS="APPLICATION"
 176 >CDL</SPAN
 177 > script would look like this:</P
 178 ><TABLE
 179 BORDER="5"
 180 BGCOLOR="#E0E0F0"
 181 WIDTH="70%"
 182 ><TR
 183 ><TD
 184 ><PRE
 185 CLASS="PROGRAMLISTING"
 186 >cdl_package CYGPKG_ERROR {
 187     display       "Common error code support"
 188     compile       strerror.cxx
 189     include_dir   cyg/error
 190     description   "
 191         This package contains the common list of error and
 192         status codes. It is held centrally to allow
 193         packages to interchange error codes and status
 194         codes in a common way, rather than each package
 195         having its own conventions for error/status
 196         reporting. The error codes are modelled on the
 197         POSIX style naming e.g. EINVAL etc. This package
 198         also provides the standard strerror() function to
 199         convert error codes to textual representation."
 200 }</PRE
 201 ></TD
 202 ></TR
 203 ></TABLE
 204 ><P
 205 >This describes a single package, the error code package, which does
 206 not have any sub-components or configuration options. The package has
 207 an internal name, <TT
 208 CLASS="VARNAME"
 209 >CYGPKG_ERROR</TT
 210 >, which can be
 211 referenced in other <SPAN
 212 CLASS="APPLICATION"
 213 >CDL</SPAN
 214 > scripts using e.g.
 215 <TT
 216 CLASS="LITERAL"
 217 >requires&nbsp;CYGPKG_ERROR</TT
 218 >. There will also be a
 219 <TT
 220 CLASS="LITERAL"
 221 >#define</TT
 222 > for this symbol in a configuration header
 223 file. In addition to the package name, this script provides a number
 224 of properties for the package as a whole. The <SPAN
 225 CLASS="PROPERTY"
 226 >display</SPAN
 227 > property
 228 provides a short description. The <SPAN
 229 CLASS="PROPERTY"
 230 >description</SPAN
 231 > property involves a
 232 rather longer one, for when users need a bit more information. The
 233 <SPAN
 234 CLASS="PROPERTY"
 235 >compile</SPAN
 236 > and <SPAN
 237 CLASS="PROPERTY"
 238 >include_dir</SPAN
 239 > properties list the consequences of this
 240 package at build-time. The package appears to lack any on-line
 241 documentation. </P
 242 ><P
 243 >Packages could be even simpler than this. If the package only provides
 244 an interface and there are no files to be compiled then there is no
 245 need for a <SPAN
 246 CLASS="PROPERTY"
 247 >compile</SPAN
 248 > property. Alternatively if there are no exported
 249 header files, or if the exported header files should go to the
 250 top-level of the <TT
 251 CLASS="FILENAME"
 252 >install/include</TT
 253 > directory, then there is
 254 no need for an <SPAN
 255 CLASS="PROPERTY"
 256 >include_dir</SPAN
 257 > property. Strictly speaking the
 258 <SPAN
 259 CLASS="PROPERTY"
 260 >description</SPAN
 261 > and <SPAN
 262 CLASS="PROPERTY"
 263 >display</SPAN
 264 > properties are optional as well, although
 265 application developers would not appreciate the resulting lack of
 266 information about what the package is supposed to do.</P
 267 ><P
 268 >However many packages tend to be a bit more complicated than the error
 269 package, containing various sub-components and configuration options.
 270 These are also defined in the <SPAN
 271 CLASS="APPLICATION"
 272 >CDL</SPAN
 273 > scripts and in much the same way
 274 as the package. For example, the following excerpt comes from the
 275 infrastructure package:</P
 276 ><TABLE
 277 BORDER="5"
 278 BGCOLOR="#E0E0F0"
 279 WIDTH="70%"
 280 ><TR
 281 ><TD
 282 ><PRE
 283 CLASS="PROGRAMLISTING"
 284 >cdl_component CYGDBG_INFRA_DEBUG_TRACE_ASSERT_BUFFER {
 285     display       "Buffered tracing"
 286     default_value 1
 287     active_if     CYGDBG_USE_TRACING
 288     description   "
 289         An output module which buffers output from tracing and
 290         assertion events. The stored messages are output when an
 291         assert fires, or CYG_TRACE_PRINT() (defined in
 292         &lt;cyg/infra/cyg_trac.h&gt;) is called. Of course, there will
 293         only be stored messages if tracing per se (CYGDBG_USE_TRACING)
 294         is enabled above."
 295
 296     cdl_option CYGDBG_INFRA_DEBUG_TRACE_BUFFER_SIZE {
 297         display       "Trace buffer size"
 298         flavor        data
 299         default_value 32
 300         legal_values  5 to 65535
 301         description   "
 302             The size of the trace buffer. This counts the number of
 303             trace records stored. When the buffer fills it either
 304             wraps, stops recording, or generates output."
 305     }
 306
 307     &#8230;
 308 }</PRE
 309 ></TD
 310 ></TR
 311 ></TABLE
 312 ><P
 313 >Like a <TT
 314 CLASS="LITERAL"
 315 >cdl_package</TT
 316 >, a <TT
 317 CLASS="LITERAL"
 318 >cdl_component</TT
 319 > has a name and a body. The
 320 body contains various properties for that component, and may also
 321 contain sub-components or options. Similarly a <TT
 322 CLASS="LITERAL"
 323 >cdl_option</TT
 324 > has a
 325 name and a body of properties. This example lists a number of
 326 new properties: <SPAN
 327 CLASS="PROPERTY"
 328 >default_value</SPAN
 329 >, <SPAN
 330 CLASS="PROPERTY"
 331 >active_if</SPAN
 332 >, <SPAN
 333 CLASS="PROPERTY"
 334 >flavor</SPAN
 335 > and
 336 <SPAN
 337 CLASS="PROPERTY"
 338 >legal_values</SPAN
 339 >. The meaning of most of these should be fairly obvious.
 340 The next sections describe the various <SPAN
 341 CLASS="APPLICATION"
 342 >CDL</SPAN
 343 > commands and properties. </P
 344 ><P
 345 >There is one additional and very important point: <SPAN
 346 CLASS="APPLICATION"
 347 >CDL</SPAN
 348 > is not a
 349 completely new language; instead it is implemented as an extension of
 350 the existing <SPAN
 351 CLASS="APPLICATION"
 352 >Tcl</SPAN
 353 > scripting language. The syntax of a <SPAN
 354 CLASS="APPLICATION"
 355 >CDL</SPAN
 356 > script is
 357 <SPAN
 358 CLASS="APPLICATION"
 359 >Tcl</SPAN
 360 > syntax, which is described below. In addition some of the more
 361 advanced facilities of <SPAN
 362 CLASS="APPLICATION"
 363 >CDL</SPAN
 364 > involve embedded fragments of <SPAN
 365 CLASS="APPLICATION"
 366 >Tcl</SPAN
 367 > code,
 368 for example there is a <SPAN
 369 CLASS="PROPERTY"
 370 >define_proc</SPAN
 371 > property which specifies some
 372 code that needs to be executed when the component framework generates
 373 the configuration header files.</P
 374 ></DIV
 375 ></DIV
 376 ><DIV
 377 CLASS="NAVFOOTER"
 378 ><HR
 379 ALIGN="LEFT"
 380 WIDTH="100%"><TABLE
 381 SUMMARY="Footer navigation table"
 382 WIDTH="100%"
 383 BORDER="0"
 384 CELLPADDING="0"
 385 CELLSPACING="0"
 386 ><TR
 387 ><TD
 388 WIDTH="33%"
 389 ALIGN="left"
 390 VALIGN="top"
 391 ><A
 392 HREF="package.distrib.html"
 393 ACCESSKEY="P"
 394 >Prev</A
 395 ></TD
 396 ><TD
 397 WIDTH="34%"
 398 ALIGN="center"
 399 VALIGN="top"
 400 ><A
 401 HREF="cdl-guide.html"
 402 ACCESSKEY="H"
 403 >Home</A
 404 ></TD
 405 ><TD
 406 WIDTH="33%"
 407 ALIGN="right"
 408 VALIGN="top"
 409 ><A
 410 HREF="language.commands.html"
 411 ACCESSKEY="N"
 412 >Next</A
 413 ></TD
 414 ></TR
 415 ><TR
 416 ><TD
 417 WIDTH="33%"
 418 ALIGN="left"
 419 VALIGN="top"
 420 >Making a Package Distribution</TD
 421 ><TD
 422 WIDTH="34%"
 423 ALIGN="center"
 424 VALIGN="top"
 425 >&nbsp;</TD
 426 ><TD
 427 WIDTH="33%"
 428 ALIGN="right"
 429 VALIGN="top"
 430 >CDL Commands</TD
 431 ></TR
 432 ></TABLE
 433 ></DIV
 434 ></BODY
 435 ></HTML
 436 >