doc/html/cdl-guide/ref.compile.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 >compile</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="calculated"
  26 HREF="ref.calculated.html"><LINK
  27 REL="NEXT"
  28 TITLE="default_value"
  29 HREF="ref.default-value.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.calculated.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.default-value.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.COMPILE"><SPAN
  86 CLASS="PROPERTY"
  87 >compile</SPAN
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN3815"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Property <SPAN
  97 CLASS="PROPERTY"
  98 >compile</SPAN
  99 >&nbsp;--&nbsp;List the source files that should be built if this option
 100 is active and enabled.</DIV
 101 ><DIV
 102 CLASS="REFSYNOPSISDIV"
 103 ><A
 104 NAME="AEN3819"><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     compile [-library=libxxx.a] &lt;list of files&gt;
 116     &#8230;
 117 }</PRE
 118 ></TD
 119 ></TR
 120 ></TABLE
 121 ></DIV
 122 ><DIV
 123 CLASS="REFSECT1"
 124 ><A
 125 NAME="AEN3821"
 126 ></A
 127 ><H2
 128 >Description</H2
 129 ><P
 130 >The <SPAN
 131 CLASS="PROPERTY"
 132 >compile</SPAN
 133 > property allows component developers to specify source
 134 files which should be compiled and added to one of the target
 135 libraries. Usually each source file will end up the library
 136 <TT
 137 CLASS="FILENAME"
 138 >libtarget.a</TT
 139 >. It is possible for component writers
 140 to specify an alternative library for an entire package using the
 141 <A
 142 HREF="ref.library.html"
 143 ><SPAN
 144 CLASS="PROPERTY"
 145 >library</SPAN
 146 ></A
 147 > property. Alternatively
 148 the desired library can be specified on the <SPAN
 149 CLASS="PROPERTY"
 150 >compile</SPAN
 151 > line itself. For
 152 example, to add a particular source file to the
 153 <TT
 154 CLASS="FILENAME"
 155 >libextras.a</TT
 156 > library the following could be used:</P
 157 ><TABLE
 158 BORDER="5"
 159 BGCOLOR="#E0E0F0"
 160 WIDTH="70%"
 161 ><TR
 162 ><TD
 163 ><PRE
 164 CLASS="PROGRAMLISTING"
 165 >cdl_package CYGPKG_IO_SERIAL {
 166     &#8230;
 167     compile -library=libextras.a common/tty.c
 168 }</PRE
 169 ></TD
 170 ></TR
 171 ></TABLE
 172 ><P
 173 >Details of the build process including such issues as compiler flags
 174 and the order in which things happen can be found in
 175 <A
 176 HREF="build.html"
 177 >Chapter 4</A
 178 >. </P
 179 ><P
 180 ><SPAN
 181 CLASS="PROPERTY"
 182 >compile</SPAN
 183 > properties can occur in any of <TT
 184 CLASS="LITERAL"
 185 >cdl_option</TT
 186 >,
 187 <TT
 188 CLASS="LITERAL"
 189 >cdl_component</TT
 190 >, <TT
 191 CLASS="LITERAL"
 192 >cdl_package</TT
 193 > or <TT
 194 CLASS="LITERAL"
 195 >cdl_interface</TT
 196 >. A <SPAN
 197 CLASS="PROPERTY"
 198 >compile</SPAN
 199 >
 200 property has effect if and only if the entity that contains it is
 201 active and enabled. Typically the body of a <TT
 202 CLASS="LITERAL"
 203 >cdl_package</TT
 204 > will define
 205 any source files that need to be built irrespective of individual
 206 options, and each <TT
 207 CLASS="LITERAL"
 208 >cdl_component</TT
 209 >, <TT
 210 CLASS="LITERAL"
 211 >cdl_option</TT
 212 >, and <TT
 213 CLASS="LITERAL"
 214 >cdl_interface</TT
 215 >
 216 will define source files that are more specific. A single <SPAN
 217 CLASS="PROPERTY"
 218 >compile</SPAN
 219 >
 220 property can list any number of source files, all destined for the
 221 same library. A <TT
 222 CLASS="LITERAL"
 223 >cdl_option</TT
 224 > or other entity can contain multiple
 225 <SPAN
 226 CLASS="PROPERTY"
 227 >compile</SPAN
 228 > properties, each of which can specify a different library.
 229 It is possible for a given source file to be specified in <SPAN
 230 CLASS="PROPERTY"
 231 >compile</SPAN
 232 >
 233 properties for several different options, in which case the source
 234 file will get built if any of these options are active and enabled.</P
 235 ><P
 236 >If the package follows the <A
 237 HREF="package.html#PACKAGE.HIERARCHY"
 238 >directory
 239 layout conventions</A
 240 > then the configuration tools will search for
 241 the specified source files first in the
 242 <TT
 243 CLASS="FILENAME"
 244 >src</TT
 245 > subdirectory of the
 246 package, then relative to the package directory itself. </P
 247 ><DIV
 248 CLASS="NOTE"
 249 ><BLOCKQUOTE
 250 CLASS="NOTE"
 251 ><P
 252 ><B
 253 >Note: </B
 254 >A shortcoming of the current specification of <SPAN
 255 CLASS="PROPERTY"
 256 >compile</SPAN
 257 > properties is
 258 that there is no easy way to specify source files that should be built
 259 unless an option is enabled. It would sometimes be useful to be able
 260 to say: &#8220;if option <TT
 261 CLASS="LITERAL"
 262 >A</TT
 263 > is enabled then compile
 264 file <TT
 265 CLASS="FILENAME"
 266 >x.c</TT
 267 >, otherwise compile file
 268 <TT
 269 CLASS="FILENAME"
 270 >y.c</TT
 271 >. There are two simple ways of achieving this: </P
 272 ><P
 273 ></P
 274 ><UL
 275 ><LI
 276 ><P
 277 >Always compile <TT
 278 CLASS="FILENAME"
 279 >y.c</TT
 280 >, typically by listing it in
 281 the body of the <TT
 282 CLASS="LITERAL"
 283 >cdl_package</TT
 284 >, but use
 285 <TT
 286 CLASS="LITERAL"
 287 >#ifndef&nbsp;A</TT
 288 > to produce an empty object file if
 289 option <TT
 290 CLASS="LITERAL"
 291 >A</TT
 292 > is not enabled. This has the big
 293 disadvantage that the file always gets compiled and hence for some
 294 configurations builds will take longer than necessary.</P
 295 ></LI
 296 ><LI
 297 ><P
 298 >Use a <SPAN
 299 CLASS="PROPERTY"
 300 >calculated</SPAN
 301 > option whose value is <TT
 302 CLASS="LITERAL"
 303 >!A</TT
 304 >, and
 305 have a <TT
 306 CLASS="LITERAL"
 307 >compile&nbsp;y.c</TT
 308 > property in its body. This
 309 has the big disadvantage of adding another calculated option to the
 310 configuration.</P
 311 ></LI
 312 ></UL
 313 ><P
 314 >It is likely that this will be resolved in the future, possibly by
 315 using some sort of expression as the argument to a <SPAN
 316 CLASS="PROPERTY"
 317 >compile</SPAN
 318 > property.</P
 319 ></BLOCKQUOTE
 320 ></DIV
 321 ><DIV
 322 CLASS="NOTE"
 323 ><BLOCKQUOTE
 324 CLASS="NOTE"
 325 ><P
 326 ><B
 327 >Note: </B
 328 >Currently it is not possible to control the priority of a <SPAN
 329 CLASS="PROPERTY"
 330 >compile</SPAN
 331 >
 332 property, in other words the order in which a file gets compiled
 333 relative to other build steps. This functionality might prove useful
 334 for complicated packages and should be added.</P
 335 ></BLOCKQUOTE
 336 ></DIV
 337 ></DIV
 338 ><DIV
 339 CLASS="REFSECT1"
 340 ><A
 341 NAME="AEN3874"
 342 ></A
 343 ><H2
 344 >Example</H2
 345 ><TABLE
 346 BORDER="5"
 347 BGCOLOR="#E0E0F0"
 348 WIDTH="70%"
 349 ><TR
 350 ><TD
 351 ><PRE
 352 CLASS="PROGRAMLISTING"
 353 >cdl_package CYGPKG_INFRA {
 354     display       "Infrastructure"
 355     include_dir   cyg/infra
 356     description   "
 357         Common types and useful macros.
 358         Tracing and assertion facilities.
 359         Package startup options."
 360
 361     compile startup.cxx prestart.cxx pkgstart.cxx userstart.cxx \
 362             dummyxxmain.cxx memcpy.c memset.c delete.cxx \
 363             diag.cxx tcdiag.cxx
 364 }</PRE
 365 ></TD
 366 ></TR
 367 ></TABLE
 368 ></DIV
 369 ><DIV
 370 CLASS="REFSECT1"
 371 ><A
 372 NAME="AEN3877"
 373 ></A
 374 ><H2
 375 >See Also</H2
 376 ><P
 377 >Properties <A
 378 HREF="ref.make.html"
 379 >make</A
 380 >,
 381 <A
 382 HREF="ref.make-object.html"
 383 >make_object</A
 384 > and
 385 <A
 386 HREF="ref.library.html"
 387 >library</A
 388 >.</P
 389 ></DIV
 390 ><DIV
 391 CLASS="NAVFOOTER"
 392 ><HR
 393 ALIGN="LEFT"
 394 WIDTH="100%"><TABLE
 395 SUMMARY="Footer navigation table"
 396 WIDTH="100%"
 397 BORDER="0"
 398 CELLPADDING="0"
 399 CELLSPACING="0"
 400 ><TR
 401 ><TD
 402 WIDTH="33%"
 403 ALIGN="left"
 404 VALIGN="top"
 405 ><A
 406 HREF="ref.calculated.html"
 407 ACCESSKEY="P"
 408 >Prev</A
 409 ></TD
 410 ><TD
 411 WIDTH="34%"
 412 ALIGN="center"
 413 VALIGN="top"
 414 ><A
 415 HREF="cdl-guide.html"
 416 ACCESSKEY="H"
 417 >Home</A
 418 ></TD
 419 ><TD
 420 WIDTH="33%"
 421 ALIGN="right"
 422 VALIGN="top"
 423 ><A
 424 HREF="ref.default-value.html"
 425 ACCESSKEY="N"
 426 >Next</A
 427 ></TD
 428 ></TR
 429 ><TR
 430 ><TD
 431 WIDTH="33%"
 432 ALIGN="left"
 433 VALIGN="top"
 434 ><SPAN
 435 CLASS="PROPERTY"
 436 >calculated</SPAN
 437 ></TD
 438 ><TD
 439 WIDTH="34%"
 440 ALIGN="center"
 441 VALIGN="top"
 442 ><A
 443 HREF="reference.html"
 444 ACCESSKEY="U"
 445 >Up</A
 446 ></TD
 447 ><TD
 448 WIDTH="33%"
 449 ALIGN="right"
 450 VALIGN="top"
 451 ><SPAN
 452 CLASS="PROPERTY"
 453 >default_value</SPAN
 454 ></TD
 455 ></TR
 456 ></TABLE
 457 ></DIV
 458 ></BODY
 459 ></HTML
 460 >