doc/html/cdl-guide/build.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 Build Process</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="Updating the ecos.db database"
  23 HREF="language.database.html"><LINK
  24 REL="NEXT"
  25 TITLE="Configuration Header File Generation"
  26 HREF="build.headers.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="language.database.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="build.headers.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="BUILD">Chapter 4. The Build Process</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="build.html#BUILD.OUTLINE"
  95 >Build Tree Generation</A
  96 ></DT
  97 ><DT
  98 ><A
  99 HREF="build.headers.html"
 100 >Configuration Header File Generation</A
 101 ></DT
 102 ><DT
 103 ><A
 104 HREF="build.make.html"
 105 >Building eCos</A
 106 ></DT
 107 ><DT
 108 ><A
 109 HREF="build.tests.html"
 110 >Building Test Cases</A
 111 ></DT
 112 ></DL
 113 ></DIV
 114 ><P
 115 >Some <SPAN
 116 CLASS="APPLICATION"
 117 >CDL</SPAN
 118 > properties describe the consequences of manipulating
 119 configuration options. There are two main types of consequences.
 120 Typically enabling a configuration option results in one or more
 121 <TT
 122 CLASS="LITERAL"
 123 >#define's</TT
 124 > in a configuration header file, and
 125 properties that affect this include <SPAN
 126 CLASS="PROPERTY"
 127 >define</SPAN
 128 >, <SPAN
 129 CLASS="PROPERTY"
 130 >define_proc</SPAN
 131 > and
 132 <SPAN
 133 CLASS="PROPERTY"
 134 >no_define</SPAN
 135 >. Enabling a configuration option can also affect the build
 136 process, primarily determining which files get built and added to the
 137 appropriate library. Properties related to the build process include
 138 <SPAN
 139 CLASS="PROPERTY"
 140 >compile</SPAN
 141 > and <SPAN
 142 CLASS="PROPERTY"
 143 >make</SPAN
 144 >. This chapter describes the whole build process,
 145 including details such as compiler flags and custom build steps.</P
 146 ><P
 147 >Part of the overall design of the <SPAN
 148 CLASS="APPLICATION"
 149 >eCos</SPAN
 150 > component framework is that
 151 it can interact with a number of different build systems. The most
 152 obvious of these is <SPAN
 153 CLASS="APPLICATION"
 154 >GNU
 155 make</SPAN
 156 >:the component framework can generate one or more
 157 makefiles, and the user can then build the various packages simply by
 158 invoking <SPAN
 159 CLASS="APPLICATION"
 160 >make</SPAN
 161 >. However it
 162 should also be possible to build <SPAN
 163 CLASS="APPLICATION"
 164 >eCos</SPAN
 165 > by other means: the
 166 component framework can be queried about what is involved in building
 167 a given configuration, and this information can then be fed into the
 168 desired build system. Component writers should be aware of this
 169 possibility. Most packages will not be affected because the <SPAN
 170 CLASS="PROPERTY"
 171 >compile</SPAN
 172 >
 173 property can be used to provide all the required information, but care
 174 has to be taken when writing custom build steps.</P
 175 ><DIV
 176 CLASS="SECT1"
 177 ><H1
 178 CLASS="SECT1"
 179 ><A
 180 NAME="BUILD.OUTLINE">Build Tree Generation</H1
 181 ><P
 182 >It is necessary to create an <SPAN
 183 CLASS="APPLICATION"
 184 >eCos</SPAN
 185 > configuration before anything can
 186 be built. With some tools such as the graphical configuration tool
 187 this configuration will be created in memory, and it is not essential
 188 to produce an <TT
 189 CLASS="FILENAME"
 190 >ecos.ecc</TT
 191 > savefile first (although
 192 it is still very desirable to generate such a savefile at some point,
 193 to allow the configuration to be re-loaded later on). With other tools
 194 the savefile is generated first, for example using
 195 <TT
 196 CLASS="LITERAL"
 197 >ecosconfig&nbsp;new</TT
 198 >, and then a build tree is
 199 generated using <TT
 200 CLASS="LITERAL"
 201 >ecosconfig&nbsp;tree</TT
 202 >. The savefile
 203 contains all the information needed to recreate a configuration.</P
 204 ><P
 205 >An <SPAN
 206 CLASS="APPLICATION"
 207 >eCos</SPAN
 208 > build actually involves three separate trees. The component
 209 repository acts as the source tree, and for application developers
 210 this should be considered a read-only resource. The build tree is
 211 where all intermediate files, especially object files, are created.
 212 The install tree is where the main library
 213 <TT
 214 CLASS="FILENAME"
 215 >libtarget.a</TT
 216 >, the exported header files, and
 217 similar files end up. Following a successful build it is possible to
 218 take just the install tree and use it for developing an application:
 219 none of the files in the component repository or the build tree are
 220 needed for that. The build tree will be needed again only if the user
 221 changes the configuration. However the install tree does not contain
 222 copies of all of the documentation for the various packages, instead
 223 the documentation is kept only in the component repository.</P
 224 ><P
 225 >By default the build tree, the install tree, and the
 226 <TT
 227 CLASS="FILENAME"
 228 >ecos.ecc</TT
 229 > savefile all reside in the same
 230 directory tree. This is not a requirement, both the install tree and
 231 the savefile can be anywhere in the file system.</P
 232 ><P
 233 >It is worth noting that the component framework does not separate the
 234 usual <TT
 235 CLASS="LITERAL"
 236 >make</TT
 237 > and <TT
 238 CLASS="LITERAL"
 239 >make&nbsp;install</TT
 240 >
 241 stages. A build always populates the install tree, and any
 242 <TT
 243 CLASS="LITERAL"
 244 >make&nbsp;install</TT
 245 > step would be redundant.</P
 246 ><P
 247 >The install tree will always begin with two directories, <TT
 248 CLASS="FILENAME"
 249 >include</TT
 250 > for the exported header files and
 251 <TT
 252 CLASS="FILENAME"
 253 >lib</TT
 254 > for the main library
 255 <TT
 256 CLASS="FILENAME"
 257 >libtarget.a</TT
 258 > and other files
 259 such as the linker script. In addition there will be a subdirectory
 260 <TT
 261 CLASS="FILENAME"
 262 >include/pkgconf</TT
 263 > containing the
 264 configuration header files, which are generated or updated at the same
 265 time the build tree is created or updated. More details of header file
 266 generation are given below. Additional <TT
 267 CLASS="FILENAME"
 268 >include</TT
 269 > subdirectories such as <TT
 270 CLASS="FILENAME"
 271 >sys</TT
 272 > and <TT
 273 CLASS="FILENAME"
 274 >cyg/kernel</TT
 275 > will be created during the
 276 first build, when each package's exported header files are copied to
 277 the install tree. The install tree may also end up with additional
 278 subdirectories during a build, for example as a result of custom build
 279 steps. </P
 280 ><P
 281 >The component framework does not define the structure of the build
 282 tree, and this may vary between build systems. It can be assumed that
 283 each package in the configuration will have its own directory in the
 284 build tree, and that this directory will be used for storing the
 285 package's object files and as the current directory for any build
 286 steps for that package. This avoids problems when custom build steps
 287 from different packages generate intermediate files which happen to
 288 have the same name.</P
 289 ><P
 290 >Some build systems may allow application developers to copy a source
 291 file from the component repository to the build tree and edit the
 292 copy. This allows users to experiment with small changes, for example
 293 to add a couple of lines of debugging to a package, without having to
 294 modify the master copy in the component repository which could be
 295 shared by several projects or several people. Functionality such as
 296 this is transparent to component writers, and it is the responsibility
 297 of the build system to make sure that the right thing happens.</P
 298 ><DIV
 299 CLASS="NOTE"
 300 ><BLOCKQUOTE
 301 CLASS="NOTE"
 302 ><P
 303 ><B
 304 >Note: </B
 305 >There are some unresolved issues related to the build tree and install
 306 tree. Specifically, when updating an existing build or install tree,
 307 what should happen to unexpected files or directories? Suppose the
 308 user started with a configuration that included the math library, and
 309 the install tree contains header files <TT
 310 CLASS="FILENAME"
 311 >include/math.h</TT
 312 > and <TT
 313 CLASS="FILENAME"
 314 >include/sys/ieeefp.h</TT
 315 >. The user then removed
 316 the math library from the configuration and is updating the build
 317 tree. It is now desirable to remove these header files from the
 318 install tree, so that if any application code still attempts to use
 319 the math library this will fail at compile time rather than at link
 320 time. There will also be some object files in the existing
 321 <TT
 322 CLASS="LITERAL"
 323 >libtarget.a</TT
 324 > library which are no longer
 325 appropriate, and there may be other files in the install tree as a
 326 result of custom build steps. The build tree will still contain a
 327 directory for the math library, which no longer serves any purpose.</P
 328 ><P
 329 >However, it is also possible that some of the files in the build tree
 330 or the install tree were placed there by the user, in which case
 331 removing them automatically would be a bad idea.</P
 332 ><P
 333 >At present the component framework does not keep track of exactly what
 334 should be present in the build and install trees, so it cannot readily
 335 determine which files or library members are obsolete and can safely
 336 be removed, and which ones are unexpected and need to be reported to
 337 the user. This will be addressed in a future release of the system.</P
 338 ></BLOCKQUOTE
 339 ></DIV
 340 ></DIV
 341 ></DIV
 342 ><DIV
 343 CLASS="NAVFOOTER"
 344 ><HR
 345 ALIGN="LEFT"
 346 WIDTH="100%"><TABLE
 347 SUMMARY="Footer navigation table"
 348 WIDTH="100%"
 349 BORDER="0"
 350 CELLPADDING="0"
 351 CELLSPACING="0"
 352 ><TR
 353 ><TD
 354 WIDTH="33%"
 355 ALIGN="left"
 356 VALIGN="top"
 357 ><A
 358 HREF="language.database.html"
 359 ACCESSKEY="P"
 360 >Prev</A
 361 ></TD
 362 ><TD
 363 WIDTH="34%"
 364 ALIGN="center"
 365 VALIGN="top"
 366 ><A
 367 HREF="cdl-guide.html"
 368 ACCESSKEY="H"
 369 >Home</A
 370 ></TD
 371 ><TD
 372 WIDTH="33%"
 373 ALIGN="right"
 374 VALIGN="top"
 375 ><A
 376 HREF="build.headers.html"
 377 ACCESSKEY="N"
 378 >Next</A
 379 ></TD
 380 ></TR
 381 ><TR
 382 ><TD
 383 WIDTH="33%"
 384 ALIGN="left"
 385 VALIGN="top"
 386 >Updating the <SPAN
 387 CLASS="DATABASE"
 388 >ecos.db</SPAN
 389 > database</TD
 390 ><TD
 391 WIDTH="34%"
 392 ALIGN="center"
 393 VALIGN="top"
 394 >&nbsp;</TD
 395 ><TD
 396 WIDTH="33%"
 397 ALIGN="right"
 398 VALIGN="top"
 399 >Configuration Header File Generation</TD
 400 ></TR
 401 ></TABLE
 402 ></DIV
 403 ></BODY
 404 ></HTML
 405 >