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. -->
12 >The Build Process</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="The eCos Component Writer's Guide"
20 HREF="cdl-guide.html"><LINK
22 TITLE="Updating the ecos.db database"
23 HREF="language.database.html"><LINK
25 TITLE="Configuration Header File Generation"
26 HREF="build.headers.html"></HEAD
37 SUMMARY="Header navigation table"
49 > Component Writer's Guide</TH
57 HREF="language.database.html"
71 HREF="build.headers.html"
84 NAME="BUILD">Chapter 4. The Build Process</H1
94 HREF="build.html#BUILD.OUTLINE"
95 >Build Tree Generation</A
99 HREF="build.headers.html"
100 >Configuration Header File Generation</A
104 HREF="build.make.html"
109 HREF="build.tests.html"
110 >Building Test Cases</A
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
124 > in a configuration header file, and
125 properties that affect this include <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
144 >. This chapter describes the whole build process,
145 including details such as compiler flags and custom build steps.</P
147 >Part of the overall design of the <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
156 >:the component framework can generate one or more
157 makefiles, and the user can then build the various packages simply by
162 should also be possible to build <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
173 property can be used to provide all the required information, but care
174 has to be taken when writing custom build steps.</P
180 NAME="BUILD.OUTLINE">Build Tree Generation</H1
182 >It is necessary to create an <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
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
197 >ecosconfig new</TT
198 >, and then a build tree is
201 >ecosconfig tree</TT
203 contains all the information needed to recreate a configuration.</P
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
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
225 >By default the build tree, the install tree, and the
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
233 >It is worth noting that the component framework does not separate the
239 >make install</TT
241 stages. A build always populates the install tree, and any
244 >make install</TT
245 > step would be redundant.</P
247 >The install tree will always begin with two directories, <TT
250 > for the exported header files and
254 > for the main library
259 such as the linker script. In addition there will be a subdirectory
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
269 > subdirectories such as <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
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
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
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
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
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
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
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
347 SUMMARY="Footer navigation table"
358 HREF="language.database.html"
367 HREF="cdl-guide.html"
376 HREF="build.headers.html"
399 >Configuration Header File Generation</TD