doc/html/cdl-guide/ref.define-proc.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 >define_proc</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="define_header"
  26 HREF="ref.define-header.html"><LINK
  27 REL="NEXT"
  28 TITLE="description"
  29 HREF="ref.description.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.define-header.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.description.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.DEFINE-PROC"><SPAN
  86 CLASS="PROPERTY"
  87 >define_proc</SPAN
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN4169"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Property <SPAN
  97 CLASS="PROPERTY"
  98 >define_proc</SPAN
  99 >&nbsp;--&nbsp;Use a fragment of Tcl code to output additional data to
 100 configuration header files.</DIV
 101 ><DIV
 102 CLASS="REFSYNOPSISDIV"
 103 ><A
 104 NAME="AEN4173"><H2
 105 >Synopsis</H2
 106 ><TABLE
 107 BORDER="5"
 108 BGCOLOR="#E0E0F0"
 109 WIDTH="70%"
 110 ><TR
 111 ><TD
 112 ><PRE
 113 CLASS="SYNOPSIS"
 114 >cdl_option &lt;name&gt; {
 115     define_proc &lt;Tcl script&gt;
 116     &#8230;
 117 }</PRE
 118 ></TD
 119 ></TR
 120 ></TABLE
 121 ></DIV
 122 ><DIV
 123 CLASS="REFSECT1"
 124 ><A
 125 NAME="AEN4175"
 126 ></A
 127 ><H2
 128 >Description</H2
 129 ><P
 130 >For most configuration options it is sufficient to have an entry in
 131 the configuration header file of the form:</P
 132 ><TABLE
 133 BORDER="5"
 134 BGCOLOR="#E0E0F0"
 135 WIDTH="70%"
 136 ><TR
 137 ><TD
 138 ><PRE
 139 CLASS="PROGRAMLISTING"
 140 >#define &lt;name&gt; &lt;value&gt;</PRE
 141 ></TD
 142 ></TR
 143 ></TABLE
 144 ><P
 145 >In some cases it is desirable to perform some more complicated
 146 processing when generating a configuration header file. There are a
 147 number of CDL properties for this, including <SPAN
 148 CLASS="PROPERTY"
 149 >define_format</SPAN
 150 > and
 151 <SPAN
 152 CLASS="PROPERTY"
 153 >if_define</SPAN
 154 >. The most flexible is <SPAN
 155 CLASS="PROPERTY"
 156 >define_proc</SPAN
 157 >: this allows the
 158 component writer to specify a Tcl script that gets invoked whenever
 159 the configuration system generates the header file for the owning
 160 package. The script can output anything to the header file, for
 161 example it could generate a C data structure based on various
 162 configuration values.</P
 163 ><P
 164 >At the point that the <SPAN
 165 CLASS="PROPERTY"
 166 >define_proc</SPAN
 167 > script is invoked there will be
 168 two channels to open files, accessible via Tcl variables:
 169 <TT
 170 CLASS="LITERAL"
 171 >cdl_header</TT
 172 > is a channel to the current package's
 173 own header file for example
 174 <TT
 175 CLASS="FILENAME"
 176 >pkgconf/kernel.h</TT
 177 >;
 178 <TT
 179 CLASS="LITERAL"
 180 >cdl_system_header</TT
 181 > is a channel to the global
 182 configuration file
 183 <TT
 184 CLASS="FILENAME"
 185 >pkgconf/system.h</TT
 186 >. A typical
 187 <SPAN
 188 CLASS="PROPERTY"
 189 >define_proc</SPAN
 190 > script will use the <TT
 191 CLASS="LITERAL"
 192 >puts</TT
 193 > command to
 194 output data to one of these channels.</P
 195 ><P
 196 ><SPAN
 197 CLASS="PROPERTY"
 198 >define_proc</SPAN
 199 > properties only take effect if the current option is
 200 active and enabled. The default behavior of the configuration system
 201 for an option with the <TT
 202 CLASS="LITERAL"
 203 >bool</TT
 204 > flavor corresponds to
 205 the following <SPAN
 206 CLASS="PROPERTY"
 207 >define_proc</SPAN
 208 >:</P
 209 ><TABLE
 210 BORDER="5"
 211 BGCOLOR="#E0E0F0"
 212 WIDTH="70%"
 213 ><TR
 214 ><TD
 215 ><PRE
 216 CLASS="PROGRAMLISTING"
 217 >    cdl_option XXX {
 218         &#8230;
 219         define_proc {
 220             puts $cdl_header "#define XXX 1"
 221         }
 222 }</PRE
 223 ></TD
 224 ></TR
 225 ></TABLE
 226 ><DIV
 227 CLASS="WARNING"
 228 ><P
 229 ></P
 230 ><TABLE
 231 CLASS="WARNING"
 232 BORDER="1"
 233 WIDTH="100%"
 234 ><TR
 235 ><TD
 236 ALIGN="CENTER"
 237 ><B
 238 >Warning</B
 239 ></TD
 240 ></TR
 241 ><TR
 242 ><TD
 243 ALIGN="LEFT"
 244 ><P
 245 >In the current implementation it is not possible for a <SPAN
 246 CLASS="PROPERTY"
 247 >define_proc</SPAN
 248 >
 249 property to examine the current values of various configuration
 250 options and adapt accordingly. This is a major limitation, and will be
 251 addressed in future versions of the configuration tools.</P
 252 ></TD
 253 ></TR
 254 ></TABLE
 255 ></DIV
 256 ></DIV
 257 ><DIV
 258 CLASS="REFSECT1"
 259 ><A
 260 NAME="AEN4199"
 261 ></A
 262 ><H2
 263 >Example</H2
 264 ><TABLE
 265 BORDER="5"
 266 BGCOLOR="#E0E0F0"
 267 WIDTH="70%"
 268 ><TR
 269 ><TD
 270 ><PRE
 271 CLASS="PROGRAMLISTING"
 272 >cdl_package CYGPKG_HAL_ARM_PID {
 273     display       "ARM PID evaluation board"
 274     parent        CYGPKG_HAL_ARM
 275     define_header hal_arm_pid.h
 276     include_dir   cyg/hal
 277     hardware
 278
 279     define_proc {
 280         puts $::cdl_system_header "#define CYGBLD_HAL_TARGET_H   &lt;pkgconf/hal_arm.h&gt;"
 281         puts $::cdl_system_header "#define CYGBLD_HAL_PLATFORM_H &lt;pkgconf/hal_arm_pid.h&gt;"
 282         puts $::cdl_header ""
 283         puts $::cdl_header "#define HAL_PLATFORM_CPU    \"ARM 7TDMI\""
 284         puts $::cdl_header "#define HAL_PLATFORM_BOARD  \"PID\""
 285         puts $::cdl_header "#define HAL_PLATFORM_EXTRA  \"\""
 286         puts $::cdl_header ""
 287     }
 288     &#8230;
 289 }</PRE
 290 ></TD
 291 ></TR
 292 ></TABLE
 293 ></DIV
 294 ><DIV
 295 CLASS="REFSECT1"
 296 ><A
 297 NAME="AEN4202"
 298 ></A
 299 ><H2
 300 >See Also</H2
 301 ><P
 302 >Properties <A
 303 HREF="ref.define.html"
 304 ><SPAN
 305 CLASS="PROPERTY"
 306 >define</SPAN
 307 ></A
 308 >,
 309 <A
 310 HREF="ref.define-format.html"
 311 ><SPAN
 312 CLASS="PROPERTY"
 313 >define_format</SPAN
 314 ></A
 315 >,
 316 <A
 317 HREF="ref.define-header.html"
 318 ><SPAN
 319 CLASS="PROPERTY"
 320 >define_header</SPAN
 321 ></A
 322 >,
 323 <A
 324 HREF="ref.if-define.html"
 325 ><SPAN
 326 CLASS="PROPERTY"
 327 >if_define</SPAN
 328 ></A
 329 > and
 330 <A
 331 HREF="ref.no-define.html"
 332 ><SPAN
 333 CLASS="PROPERTY"
 334 >no_define</SPAN
 335 ></A
 336 >.</P
 337 ></DIV
 338 ><DIV
 339 CLASS="NAVFOOTER"
 340 ><HR
 341 ALIGN="LEFT"
 342 WIDTH="100%"><TABLE
 343 SUMMARY="Footer navigation table"
 344 WIDTH="100%"
 345 BORDER="0"
 346 CELLPADDING="0"
 347 CELLSPACING="0"
 348 ><TR
 349 ><TD
 350 WIDTH="33%"
 351 ALIGN="left"
 352 VALIGN="top"
 353 ><A
 354 HREF="ref.define-header.html"
 355 ACCESSKEY="P"
 356 >Prev</A
 357 ></TD
 358 ><TD
 359 WIDTH="34%"
 360 ALIGN="center"
 361 VALIGN="top"
 362 ><A
 363 HREF="cdl-guide.html"
 364 ACCESSKEY="H"
 365 >Home</A
 366 ></TD
 367 ><TD
 368 WIDTH="33%"
 369 ALIGN="right"
 370 VALIGN="top"
 371 ><A
 372 HREF="ref.description.html"
 373 ACCESSKEY="N"
 374 >Next</A
 375 ></TD
 376 ></TR
 377 ><TR
 378 ><TD
 379 WIDTH="33%"
 380 ALIGN="left"
 381 VALIGN="top"
 382 ><SPAN
 383 CLASS="PROPERTY"
 384 >define_header</SPAN
 385 ></TD
 386 ><TD
 387 WIDTH="34%"
 388 ALIGN="center"
 389 VALIGN="top"
 390 ><A
 391 HREF="reference.html"
 392 ACCESSKEY="U"
 393 >Up</A
 394 ></TD
 395 ><TD
 396 WIDTH="33%"
 397 ALIGN="right"
 398 VALIGN="top"
 399 ><SPAN
 400 CLASS="PROPERTY"
 401 >description</SPAN
 402 ></TD
 403 ></TR
 404 ></TABLE
 405 ></DIV
 406 ></BODY
 407 ></HTML
 408 >