3 <!-- =============================================================== -->
7 <!-- Description of the build system. -->
9 <!-- =============================================================== -->
10 <!-- ####COPYRIGHTBEGIN#### -->
12 <!-- =============================================================== -->
13 <!-- Copyright (C) 2000, 2001, 2002 Red Hat, Inc. -->
15 <!-- This material may be distributed only subject to the terms -->
16 <!-- and conditions set forth in the Open Publication License, v1.0 -->
17 <!-- or later (the latest version is presently available at -->
18 <!-- http://www.opencontent.org/openpub/) -->
19 <!-- Distribution of the work or derivative of the work in any -->
20 <!-- standard (paper) book form is prohibited unless prior -->
21 <!-- permission obtained from the copyright holder -->
22 <!-- =============================================================== -->
24 <!-- ####COPYRIGHTEND#### -->
25 <!-- =============================================================== -->
26 <!-- #####DESCRIPTIONBEGIN#### -->
28 <!-- Author(s): bartv -->
29 <!-- Contact(s): bartv -->
30 <!-- Date: 2000/02/06 -->
31 <!-- Version: 0.01 -->
33 <!-- ####DESCRIPTIONEND#### -->
34 <!-- =============================================================== -->
39 <title>The Build Process</title>
44 Some &CDL; properties describe the consequences of manipulating
45 configuration options. There are two main types of consequences.
46 Typically enabling a configuration option results in one or more
47 <literal>#define's</literal> in a configuration header file, and
48 properties that affect this include &define;, &define-proc; and
49 &no-define;. Enabling a configuration option can also affect the build
50 process, primarily determining which files get built and added to the
51 appropriate library. Properties related to the build process include
52 &compile; and &make;. This chapter describes the whole build process,
53 including details such as compiler flags and custom build steps.
56 Part of the overall design of the &eCos; component framework is that
57 it can interact with a number of different build systems. The most
58 obvious of these is <application class="software">GNU
59 make</application>:the component framework can generate one or more
60 makefiles, and the user can then build the various packages simply by
61 invoking <application class="software">make</application>. However it
62 should also be possible to build &eCos; by other means: the
63 component framework can be queried about what is involved in building
64 a given configuration, and this information can then be fed into the
65 desired build system. Component writers should be aware of this
66 possibility. Most packages will not be affected because the &compile;
67 property can be used to provide all the required information, but care
68 has to be taken when writing custom build steps.
72 <!-- {{{ Build Tree Generation -->
74 <sect1 id="build.outline">
75 <title>Build Tree Generation</title>
78 It is necessary to create an &eCos; configuration before anything can
79 be built. With some tools such as the graphical configuration tool
80 this configuration will be created in memory, and it is not essential
81 to produce an <filename>ecos.ecc</filename> savefile first (although
82 it is still very desirable to generate such a savefile at some point,
83 to allow the configuration to be re-loaded later on). With other tools
84 the savefile is generated first, for example using
85 <literal>ecosconfig new</literal>, and then a build tree is
86 generated using <literal>ecosconfig tree</literal>. The savefile
87 contains all the information needed to recreate a configuration.
90 An &eCos; build actually involves three separate trees. The component
91 repository acts as the source tree, and for application developers
92 this should be considered a read-only resource. The build tree is
93 where all intermediate files, especially object files, are created.
94 The install tree is where the main library
95 <filename>libtarget.a</filename>, the exported header files, and
96 similar files end up. Following a successful build it is possible to
97 take just the install tree and use it for developing an application:
98 none of the files in the component repository or the build tree are
99 needed for that. The build tree will be needed again only if the user
100 changes the configuration. However the install tree does not contain
101 copies of all of the documentation for the various packages, instead
102 the documentation is kept only in the component repository.
105 By default the build tree, the install tree, and the
106 <filename>ecos.ecc</filename> savefile all reside in the same
107 directory tree. This is not a requirement, both the install tree and
108 the savefile can be anywhere in the file system.
111 It is worth noting that the component framework does not separate the
112 usual <literal>make</literal> and <literal>make install</literal>
113 stages. A build always populates the install tree, and any
114 <literal>make install</literal> step would be redundant.
117 The install tree will always begin with two directories, <filename
118 class="directory">include</filename> for the exported header files and
119 <filename class="directory">lib</filename> for the main library
120 <filename class="directory">libtarget.a</filename> and other files
121 such as the linker script. In addition there will be a subdirectory
122 <filename class="directory">include/pkgconf</filename> containing the
123 configuration header files, which are generated or updated at the same
124 time the build tree is created or updated. More details of header file
125 generation are given below. Additional <filename
126 class="directory">include</filename> subdirectories such as <filename
127 class="directory">sys</filename> and <filename
128 class="directory">cyg/kernel</filename> will be created during the
129 first build, when each package's exported header files are copied to
130 the install tree. The install tree may also end up with additional
131 subdirectories during a build, for example as a result of custom build
135 The component framework does not define the structure of the build
136 tree, and this may vary between build systems. It can be assumed that
137 each package in the configuration will have its own directory in the
138 build tree, and that this directory will be used for storing the
139 package's object files and as the current directory for any build
140 steps for that package. This avoids problems when custom build steps
141 from different packages generate intermediate files which happen to
145 Some build systems may allow application developers to copy a source
146 file from the component repository to the build tree and edit the
147 copy. This allows users to experiment with small changes, for example
148 to add a couple of lines of debugging to a package, without having to
149 modify the master copy in the component repository which could be
150 shared by several projects or several people. Functionality such as
151 this is transparent to component writers, and it is the responsibility
152 of the build system to make sure that the right thing happens.
157 There are some unresolved issues related to the build tree and install
158 tree. Specifically, when updating an existing build or install tree,
159 what should happen to unexpected files or directories? Suppose the
160 user started with a configuration that included the math library, and
161 the install tree contains header files <filename
162 class="headerfile">include/math.h</filename> and <filename
163 class="headerfile">include/sys/ieeefp.h</filename>. The user then removed
164 the math library from the configuration and is updating the build
165 tree. It is now desirable to remove these header files from the
166 install tree, so that if any application code still attempts to use
167 the math library this will fail at compile time rather than at link
168 time. There will also be some object files in the existing
169 <literal>libtarget.a</literal> library which are no longer
170 appropriate, and there may be other files in the install tree as a
171 result of custom build steps. The build tree will still contain a
172 directory for the math library, which no longer serves any purpose.
175 However, it is also possible that some of the files in the build tree
176 or the install tree were placed there by the user, in which case
177 removing them automatically would be a bad idea.
180 At present the component framework does not keep track of exactly what
181 should be present in the build and install trees, so it cannot readily
182 determine which files or library members are obsolete and can safely
183 be removed, and which ones are unexpected and need to be reported to
184 the user. This will be addressed in a future release of the system.
191 <!-- {{{ Header File Generation -->
193 <sect1 id="build.headers">
194 <title>Configuration Header File Generation</title>
197 Configuration options can affect a build in two main ways. First,
198 enabling a configuration option or other &CDL; entity can result in
199 various files being built and added to a library, thus providing
200 functionality to the application code. However this mechanism can only
201 operate at a rather coarse grain, at the level of entire source files.
202 Hence the component framework also generates configuration header
203 files containing mainly C preprocessor <literal>#define</literal>
204 directives. Package source code can then <literal>#include</literal>
205 the appropriate header files and use <literal>#if</literal>,
206 <literal>#ifdef</literal> and <literal>#ifndef</literal> directives to
207 adapt accordingly. In this way configuration options can be used to
208 enable or disable entire functions within a source file or just a
209 single line, whichever is appropriate.
212 The configuration header files end up in the <filename
213 class="directory">include/pkgconf</filename> subdirectory of the
214 install tree. There will be one header file for the system as a whole,
215 <filename class="headerfile">pkgconf/system.h</filename>, and there will
216 be additional header files for each package, for example
217 <filename class="headerfile">pkgconf/kernel.h</filename>. The header files
218 are generated when creating or updating the build and install trees,
219 which needs to happen after every change to the configuration.
222 The component framework processes each package in the configuration
223 one at a time. The exact order in which the packages are processed is
224 not defined, so the order in which <literal>#define's</literal> will
225 end up in the global <filename
226 class="headerfile">pkgconf/system.h</filename> header may vary. However
227 for any given configuration the order should remain consistent until
228 packages are added to or removed from the system. This avoids
229 unnecessary changes to the global header file and hence unnecessary
230 rebuilds of the packages and of application code because of header
231 file dependency handling.
234 Within a given package the various components, options and interfaces
235 will be processed in the order in which they were defined in the
236 corresponding &CDL; scripts. Typically the data in the configuration
237 headers consists only of a sequence of <literal>#define's</literal> so
238 the order in which these are generated is irrelevant, but some
239 properties such as &define-proc; can be used to add arbitrary data to
240 a configuration header and hence there may be dependencies on the
241 order. It should be noted that re-parenting an option below some other
242 package has no effect on which header file will contain the
243 corresponding <literal>#define</literal>: the preprocessor directives
244 will always end up in the header file for the package that defines the
245 option, or in the global configuration header.
248 There are six properties which affect the process of generating header
250 <link linkend="ref.define-header">&define-header;</link>,
251 <link linkend="ref.no-define">&no-define;</link>,
252 <link linkend="ref.define-format">&define-format;</link>,
253 <link linkend="ref.define">&define;</link>,
254 <link linkend="ref.if-define">&if-define;</link>, and
255 <link linkend="ref.define-proc">&define-proc;</link>.
258 The &define-header; property can only occur in the body of a
259 &cdl-package; command and specifies the name of the header file which
260 should contain the package's configuration data, for example:
262 <programlisting width=72>
263 cdl_package <some_package> {
265 define_header xyzzy.h
269 Given such a &define-header; property the component framework will
270 use the file <filename class="headerfile">pkgconf/xyzzy.h</filename> for
271 the package's configuration data. If a package does not have
272 a &define-header; property then a suitable file name is constructed
273 from the package's name. This involves:
278 All characters in the package name up to and including the first
279 underscore are removed. For example <varname>CYGPKG_KERNEL</varname>
280 is converted to <literal>KERNEL</literal>, and
281 <varname>CYGPKG_HAL_ARM</varname> is converted to
282 <literal>HAL_ARM</literal>.
287 Any upper case letters in the resulting string will be converted to
288 lower case, yielding e.g. <literal>kernel</literal> and
289 <literal>hal_arm</literal>.
294 A <literal>.h</literal> suffix is appended, yielding e.g.
295 <literal>kernel.h</literal> and <literal>hal_arm.h</literal>.
300 Because of the naming restrictions on configuration options, this
301 should result in a valid filename. There is a small possibility of a
302 file name class, for example <varname>CYGPKG_PLUGH</varname> and
303 <varname>CYGPKG_plugh</varname> would both end up trying to use the
304 same header file <filename class="headerfile">pkgconf/plugh.h</filename>,
305 but the use of lower case letters for package names violates the
306 naming conventions. It is not legal to use the &define-header;
307 property to put the configuration data for several packages in a
308 single header file. The resulting behaviour is undefined.
311 Once the name of the package's header file has been determined and the
312 file has been opened, the various components, options and interfaces
313 in the package will be processed starting with the package itself. The
314 following steps are involved:
319 If the current option or other &CDL; entity is inactive or disabled,
320 the option is ignored for the purposes of header file generation.
321 <literal>#define's</literal> are only generated for options that are
322 both active and enabled.
327 The next step is to generate a default <literal>#define</literal> for
328 the current option. If this option has a &no-define; property then the
329 default <literal>#define</literal> is suppressed, and processing
330 continues for &define;, &if-define; and &define-proc; properties.
335 The header file appropriate for the default <literal>#define</literal>
336 is determined. For a &cdl-package; this will be <filename
337 class="headerfile">pkgconf/system.h</filename>, for any other option this
338 will be the package's own header file. The intention here is that
339 packages and application code can always determine which packages are
340 in the configuration by <literal>#include'ing</literal> <filename
341 class="headerfile">pkgconf/system.h</filename>. The C preprocessor lacks
342 any facilities for including a header file only if it exists, and
343 taking appropriate action otherwise.
348 For options with the flavors <literal>bool</literal> or
349 <literal>none</literal>, a single <literal>#define</literal> will be
350 generated. This takes the form:
352 <programlisting width=72>
353 #define <option> 1
358 <programlisting width=72>
359 #define CYGFUN_LIBC_TIME_POSIX 1
362 Package source code can check whether or not an option is active and
363 enabled by using the <literal>#ifdef</literal>,
364 <literal>#ifndef</literal> or <literal>#if
365 defined(…)</literal>directives.
370 For options with the flavors <literal>data</literal> or
371 <literal>booldata</literal>, either one or two
372 <literal>#define's</literal> will be generated. The first of these may
373 be affected by a &define-format; property. If this property is not
374 defined then the first <literal>#define</literal> will take the form:
376 <programlisting width=72>
377 #define <option> <value>
382 <programlisting width=72>
383 #define CYGNUM_LIBC_ATEXIT_HANDLERS 32
386 Package source code can examine this value using the
387 <literal>#if</literal> directive, or by using the symbol in
390 <programlisting width=72>
391 for (i = 0; i < CYGNUM_LIBC_ATEXIT_HANDLERS; i++) {
396 It must be noted that the <literal>#define</literal> will be generated
397 only if the corresponding option is both active and enabled. Options
398 with the <literal>data</literal> flavor are always enabled but may not
399 be active. Code like the above should be written only if it is known
400 that the symbol will always be defined, for example if the
401 corresponding source file will only get built if the containing
402 component is active and enabled. Otherwise the use of additional
403 <literal>#ifdef</literal> or similar directives will be necessary.
408 If there is a &define-format; property then this controls how the
409 option's value will appear in the header file. Given a format string
410 such as <literal>%08x</literal> and a value 42, the component
411 framework will execute the &Tcl; command
412 <literal>format %08x 42</literal> and the result will be
413 used for the <literal>#define's</literal> value. It is the
414 responsibility of the component writer to make sure that this &Tcl;
415 command will be valid given the format string and the legal values for
421 In addition a second <literal>#define</literal> may or may not be
422 generated. This will take the form:
424 <programlisting width=72>
425 #define <option>_<value>
430 <programlisting width=72>
431 #define CYGNUM_LIBC_ATEXIT_HANDLERS_32
434 The <literal>#define</literal> will be generated only if it would
435 result in a valid C preprocessor symbol. If the value is a string such
436 as <literal>"/dev/ser0"</literal> then the <literal>#define</literal>
437 would be suppressed. This second <literal>#define</literal> is not
438 particularly useful for numerical data, but can be valuable in other
439 circumstances. For example if the legal values for an option
440 <literal>XXX_COLOR</literal> are <literal>red</literal>,
441 <literal>green</literal> and <literal>blue</literal> then code like
442 the following can be used:
444 <programlisting width=72>
448 #ifdef XXX_COLOR_green
451 #ifdef XXX_COLOR_blue
456 The expression syntax provided by the C preprocessor is limited to
457 numerical data and cannot perform string comparisons. By generating
458 two <literal>#define's</literal> in this way it is possible to work
459 around this limitation of the C preprocessor. However some care has to
460 be taken: if a component writer also defined a configuration option
461 <literal>XXX_COLOR_green</literal> then there will be confusion. Since
462 such a configuration option violates the naming conventions, the
463 problem is unlikely to arise in practice.
471 For some options it may be useful to generate one or more additional
472 <literal>#define's</literal> or, in conjunction with the &no-define;
473 property, to define a symbol with a name different from the option's
474 name. This can be achieved with the &define; property, which takes the
477 <programlisting width=72>
478 define [-file=<filename>] [-format=<format>] <symbol>
483 <programlisting width=72>
487 This will result in something like:
489 <programlisting width=72>
494 The specified symbol must be a valid C preprocessor symbol. Normally
495 the <literal>#define</literal> will end up in the same header file as
496 the default one, in other words <filename
497 class="headerfile">pkgconf/system.h</filename> in the case of a
498 &cdl-package;, or the package's own header file for any other option.
499 The <literal>-file</literal> option can be used to change this. At
500 present the only legal value is <literal>system.h</literal>, for
503 <programlisting width=72>
504 define -file=system.h <symbol>
507 This will cause the <literal>#define</literal> to end up in the global
508 configuration header rather than in the package's own header. Use of
509 this facility should be avoided since it is very rarely necessary to
510 make options globally visible.
513 The &define; property takes another option,
514 <literal>-format</literal>, to provide a format string.
516 <programlisting width=72>
517 define -format=%08x <symbol>
520 This should only be used for options with the <literal>data</literal>
521 or <literal>booldata</literal> flavor, and has the same effect as the
522 &define-format; property has on the default
523 <literal>#define</literal>.
526 &define; properties are processed in the same way the default
527 <literal>#define</literal>. For options with the
528 <literal>bool</literal> or <literal>none</literal> flavors a single
529 <literal>#define</literal> will be generated using the value
530 <literal>1</literal>. For options with the <literal>data</literal> or
531 <literal>booldata</literal> flavors either one or two
532 <literal>#define's</literal> will be generated.
538 After processing all &define; properties, the component framework will
539 look for any &if-define; properties. These take the following form:
541 <programlisting width=72>
542 if_define [-file=<filename>] <symbol1> <symbol2>
547 <programlisting width=72>
548 if_define CYGSRC_KERNEL CYGDBG_USE_ASSERTS
551 The following will be generated in the configuration header file:
553 <programlisting width=72>
555 # define CYGDBG_USE_ASSERTS
559 Typical kernel source code would begin with the following construct:
561 <programlisting width=72>
562 #define CYGSRC_KERNEL 1
563 #include <pkgconf/kernel.h>
564 #include <cyg/infra/cyg_ass.h>
567 The infrastructure header file <filename
568 class="headerfile">cyg/infra/cyg_ass.h</filename> only checks for symbols
569 such as <literal>CYGDBG_USE_ASSERTS</literal>, and has no special
570 knowledge of the kernel or any other package. The &if-define; property
571 will only affect code that defines the symbol
572 <literal>CYGSRC_KERNEL</literal>, so typically only kernel source
573 code. If the option is enabled then assertion support will be enabled
574 for the kernel source code only. If the option is inactive or disabled
575 then kernel assertions will be disabled. Assertions in other packages
576 are not affected. Thus the &if-define; property allows control over
577 assertions, tracing, and similar facilities at the level of individual
578 packages, or at finer levels such as components or even single source
583 Current &eCos; packages do not yet make use of this facility. Instead
584 there is a single global configuration option
585 <varname>CYGDBG_USE_ASSERTS</varname> which is used to enable or
586 disable assertions for all packages. This issue should be addressed in
587 a future release of the system.
591 As with the &define; property, the &if-define; property takes an
592 option <literal>-file</literal> with a single legal value
593 <literal>system.h</literal>. This allows the output to be redirected
594 to <filename class="headerfile">pkgconf/system.h</filename> if and when
601 The final property that is relevant to configuration header file
602 generation is &define-proc;. This takes a single argument, a &Tcl;
603 fragment that can add arbitrary data to the global header <filename
604 class="headerfile">pkgconf/system.h</filename> and to the package's own
605 header. When the &define-proc; script is invoked two variables will be
606 set up to allow access to these headers: <literal>cdl_header</literal>
607 will be a channel to the package's own header file, for example
608 <filename class="headerfile">pkgconf/kernel.h</filename>;
609 <literal>cdl_system_header</literal> will be a channel to <filename
610 class="headerfile">pkgconf/system.h</filename>. A typical &define-proc;
611 script will use the &Tcl; <literal>puts</literal> command to output
612 data to one of these channels, for example:
614 <programlisting width=72>
615 cdl_option <name> {
618 puts $::cdl_header "#define XXX 1"
624 In the current implementation the use of &define-proc; is limited
625 because the &Tcl; script cannot access any of the configuration data.
626 Therefore the script is limited to writing constant data to the
627 configuration headers. This is a major limitation which will be
628 addressed in a future release of the component framework.
638 Generating C header files with <literal>#define's</literal> for the
639 configuration data suffices for existing packages written in some
640 combination of C, C++ and assembler. It can also be used in
641 conjunction with some other languages, for example by first passing
642 the source code through the C preprocessor and feeding the result into
643 the appropriate compiler. In future versions of the component
644 framework additional programming languages such as Java may be
645 supported, and the configuration data may also be written to files in
646 some format other than C preprocessor directives.
652 At present there is no way for application or package source code to
653 get hold of all the configuration details related to the current
654 hardware. Instead that information is spread over various different
655 configuration headers for the HAL and device driver packages, with
656 some of the information going into <filename
657 class="headerfile">pkgconf/system.h</filename>. It is possible that in
658 some future release of the system there will be another global
659 configuration header file <filename
660 class="headerfile">pkgconf/hardware.h</filename> which either contains the
661 configuration details for the various hardware-specific packages or
662 which <literal>#include's</literal> all the hardware-specific
663 configuration headers. The desirability and feasibility of such a
664 scheme are still to be determined. To avoid future incompatibility
665 problems as a result of any such changes, it is recommended that all
666 hardware packages (in other packages containing the &hardware;
667 property) use the &define-header; property to specify explicitly which
668 configuration header should be generated.
672 <sect2 id = "build.headers.system.h">
673 <title>The <filename class="headerfile">system.h</filename> Header</title>
676 Typically configuration header files are <literal>#include'd</literal>
677 only by the package's source code at build time, or by a package's
678 exported header files if the interface provided by the package may be
679 affected by a configuration option. There should be no need for
680 application code to know the details of individual configuration
681 options, instead the configuration should specifically meet the needs
685 There are always exceptions. Application code may want to adapt to
686 configuration options, for example to do different things for ROM and
687 RAM booting systems, or when it is necessary to support several
688 different target boards. This is especially true if the code in question
689 is really re-usable library code which has not been converted to an
690 eCos package, and hence cannot use any CDL facilities.
693 A major problem here is determining which packages are in the
694 configuration: attempting to <literal>#include</literal> a header file
695 such as <filename class="headerfile">pkgconf/net.h</filename>
696 when it is not known for certain that that particular package is part
697 of the configuration will result in compilation errors. The global
698 header file <filename class="headerfile">pkgconf/system.h</filename>
699 serves to provide such information, so application code can use
700 techniques like the following:
703 <programlisting width=72>
704 #include <pkgconf/system.h>
706 # include <pkgconf/net.h>
711 This will compile correctly irrespective of the eCos configuration,
712 and subsequent code can use <literal>#ifdef</literal> or similar
713 directives on <literal>CYGPKG_NET</literal> or any of the
714 configuration options in that package.
717 In addition to determining whether or not a package is present, the
718 global configuration header file can also be used to find out the
719 specific version of a package that is being used. This can be useful
720 if a more recent version exports additional functionality. It may also
721 be necessary to adapt to incompatible changes in the exported
722 interface or to changes in behaviour. For each package the
723 configuration system will typically <literal>#define</literal> three
724 symbols, for example for a V1.3.1 release:
726 <programlisting width=72>
727 #define CYGNUM_NET_VERSION_MAJOR 1
728 #define CYGNUM_NET_VERSION_MINOR 3
729 #define CYGNUM_NET_VERSION_RELEASE 1
732 There are a number of problems associated with such version
733 <literal>#define's</literal>. The first restriction is that the
734 package must follow the standard naming conventions, so the package
735 name must be of the form <literal>xxxPKG_yyy</literal>. The three
736 characters immediately preceding the first underscore must be
737 <literal>PKG</literal>, and will be replaced with
738 <literal>NUM</literal> when generating the version
739 <literal>#define's</literal>. If a package does not follow the naming
740 convention then no version <literal>#define's</literal> will be
744 Assuming the package does follow the naming conventions, the
745 configuration tools will always generate three version
746 <literal>#define's</literal> for the major, minor, and release
747 numbers. The symbol names are obtained from the package name by
748 replacing <literal>PKG</literal> with <literal>NUM</literal> and
749 appending <literal>_VERSION_MAJOR</literal>,
750 <literal>_VERSION_MINOR</literal> and
751 <literal>_VERSION_RELEASE</literal>. It is assumed that the resulting
752 symbols will not clash with any configuration option names. The values
753 for the <literal>#define's</literal> are determined by searching the
754 version string for sequences of digits, optionally preceded by a minus
755 sign. It is possible that some or all of the numbers are absent in any
756 given version string, in which case <literal>-1</literal> will be used
757 in the <literal>#define</literal>. For example, given a version string
758 of <literal>V1.12beta</literal>, the major version number is
759 <literal>1</literal>, the minor number is <literal>12</literal>, and
760 the release number is <literal>-1</literal>. Given a version string of
761 <literal>beta</literal> all three numbers would be set to
762 <literal>-1</literal>.
765 There is special case code for the version <literal>current</literal>,
766 which typically corresponds to a development version obtained via
767 anonymous CVS or similar means. The configuration system has special
768 built-in knowledge of this version, and will assume it is more recent
769 than any specific release number. The global configuration header
770 defines a special symbol <literal>CYGNUM_VERSION_CURRENT</literal>,
771 and this will be used as the major version number when version
772 <literal>current</literal> of a package is used:
774 <programlisting width=72>
775 #define CYGNUM_VERSION_CURRENT 0x7fffff00
777 #define CYGNUM_INFRA_VERSION_MAJOR CYGNUM_VERSION_CURRENT
778 #define CYGNUM_INFRA_VERSION_MINOR -1
779 #define CYGNUM_INFRA_VERSION_RELEASE -1
783 The large number used for <literal>CYGNUM_VERSION_CURRENT</literal>
784 should ensure that major version comparisons work as expected, while
785 still allowing for a small amount of arithmetic in case that proves
789 It should be noted that this implementation of version
790 <literal>#define's</literal> will not cope with all version number
791 schemes. However for many cases it should suffice.
799 <!-- {{{ The Build -->
801 <sect1 id="build.make">
802 <title>Building eCos</title>
807 The primary goal of an eCos build is to produce the library
808 <filename>libtarget.a</filename>. A typical &eCos; build will also
809 generate a number of other targets: <filename>extras.o</filename>,
810 startup code <filename>vectors.o</filename>, and a linker script. Some
811 packages may cause additional libraries or targets to be generated.
812 The basic build process involves a number of different phases with
813 corresponding priorities. There are a number of predefined priorities:
815 <informaltable frame="all" colsep=1 rowsep=1 pgwide=0>
816 <tgroup cols=2 colsep=1 rowsep=1>
817 <colspec colnum=1 align=right>
818 <colspec colnum=2 align=left>
821 <entry>Priority</entry>
822 <entry>Action</entry>
828 <entry>Export header files</entry>
832 <entry>Process &compile; properties</entry>
836 <entry>and most &make-object; custom build steps</entry>
840 <entry>Generate libraries</entry>
844 <entry>Process &make; custom build steps</entry>
851 Generation of the <filename>extras.o</filename> file, the startup code
852 and the linker script actually happens via &make; custom build steps,
853 typically defined in appropriate HAL packages. The component framework
854 has no special knowledge of these targets.
857 By default custom build steps for a &make-object; property happen
858 during the same phase as most compilations, but this can be changed
859 using a <literal>-priority</literal> option. Similarly custom build
860 steps for a &make; property happen at the end of a build, but this can
861 also be changed with a <literal>-priority</literal> option. For
862 example a priority of 50 can be used to run a custom build step
863 between the header file export phase and the main compilation phase.
864 Custom build steps are discussed in more detail below.
867 Some build systems may run several commands of the same priority in
868 parallel. For example files listed in &compile; properties may get
869 compiled in parallel, concurrently with &make-object; custom build
870 steps with default priorities. Since most of the time for an &eCos;
871 build involves processing &compile; properties, this allows builds to
872 be speeded up on suitable host hardware. All build steps for a given
873 phase will complete before the next phase is started.
879 <sect2 id="build.make.update">
880 <title>Updating the Build Tree</title>
883 Some build systems may involve a phase before the header files get
884 exported, to update the build and install trees automatically when
885 there has been a change to the configuration savefile
886 <filename>ecos.ecc</filename>. This is useful mainly for application
887 developers using the command line tools: it would allow users to
888 create the build tree only once, and after any subsequent
889 configuration changes the tree would be updated automatically by the
890 build system. The facility would be analogous to the
891 <literal>--enable-maintainer-mode</literal> option provide by the
892 <application class="software">autoconf</application> and <application
893 class="software">automake</application> programs. At present no &eCos;
894 build system implements this functionality, but it is likely to be
895 added in a future release.
901 <!-- {{{ Exporting headers -->
903 <sect2 id="build.make.export">
904 <title>Exporting Public Header Files</title>
907 The first compulsory phase involves making sure that there is an up to
908 date set of header files in the install tree. Each package can contain
909 some number of header files defining the exported interface.
910 Applications should only use exported functionality. A package can
911 also contain some number of private header files which are only of
912 interest to the implementation, and which should not be visible to
913 application code. The various packages that go into a particular
914 configuration can be spread all over the component repository. In
915 theory it might be possible to make all the exported header files
916 accessible by having a lengthy <literal>-I</literal> header file
917 search path, but this would be inconvenient both for building eCos and
918 for building applications. Instead all the relevant header files are
919 copied to a single location, the <filename
920 class="directory">include</filename> subdirectory of the install tree.
921 The process involves the following:
927 The install tree, for example <filename
928 class="directory">/usr/local/ecos/install</filename>, and its <filename
929 class="directory">include</filename> subdirectory <filename
930 class="directory">/usr/local/ecos/install/include</filename> will typically be
931 created when the build tree is generated or updated. At the same time
932 configuration header files will be written to the <filename
933 class="directory">pkgconf</filename> subdirectory, for example
935 class="directory">/usr/local/ecos/include/pkgconf</filename>, so that
936 the configuration data is visible to all the packages and to
937 application code that may wish to examine some of the configuration
943 Each package in the configuration is examined for exported header
944 files. The exact order in which the packages are processed is not
945 defined, but should not matter.
950 If the package has an <link
951 linkend="ref.include-files">&include-files;</link> property then this
952 lists all the exported header files:
954 <programlisting width=72>
955 cdl_package <some_package> {
957 include_files header1.h header2.h
961 If no arguments are given then the package does not export any header
964 <programlisting width=72>
965 cdl_package <some_package> {
971 The listed files may be in an <filename
972 class="directory">include</filename> subdirectory within the package's
973 hierarchy, or they may be relative to the package's toplevel
974 directory. The &include-files; property is intended mainly for very
975 simple packages. It can also be useful when converting existing code
976 to an &eCos; package, to avoid rearranging the sources.
981 If there is no &include-files; property then the component framework
982 will look for an <filename class="directory">include</filename>
983 subdirectory in the package, as per the layout conventions. All files,
984 including those in subdirectories, will be treated as exported header
985 files. For example, the math library package contains files <filename
986 class="headerfile">include/math.h</filename> and <filename
987 class="headerfile">include/sys/ieeefp.h</filename>, both of which will
988 be exported to the install tree.
993 As a last resort, if there is neither an &include-files; property nor
994 an <filename class="directory">include</filename> subdirectory, the
995 component framework will search the package's toplevel directory and
996 all of its subdirectories for files with one of the following
997 suffixes: <literal>.h</literal>, <literal>.hxx</literal>,
998 <literal>.inl</literal> or <literal>.inc</literal>. All such files
999 will be interpreted as exported header files.
1002 This last resort rule could cause confusion for packages which have no
1003 exported header files but which do contain one or more private header
1004 files. For example a typical device driver simply implements an
1005 existing interface rather than define a new one, so it does not need
1006 to export a header file. However it may still have one or more private
1007 header files. Such packages should use an &include-files; property
1015 If the package has one or more exported header files, the next step is
1016 to determine where the files should end up. By default all exported
1017 header files will just end up relative to the install tree's <filename
1018 class="directory">include</filename> subdirectory. For example the
1019 math library's <filename class="headerfile">math.h</filename> header
1020 would end up as <filename>/usr/local/ecos/include/math.h</filename>,
1021 and the <filename class="headerfile">sys/ieeefp.h</filename> header
1023 <filename>/usr/local/ecos/include/sys/ieeefp.h</filename>. This
1024 behaviour is correct for packages like the C library where the
1025 interface is defined by appropriate standards. For other packages this
1026 behaviour can lead to file name clashes, and the <link
1027 linkend="ref.include-dir">&include-dir;</link> property should be used
1030 <programlisting width=72>
1031 cdl_package CYGPKG_KERNEL {
1032 include_dir cyg/kernel
1036 This means that the kernel's exported header file
1037 <filename>include/kapi.h</filename> should be copied to
1038 <filename>/usr/local/ecos/include/cyg/kernel/kapi.h</filename>, where
1039 it is very unlikely to clash with a header file from some other
1045 For typical application developers there will be little or no need for
1046 the installed header files to change after the first build. Changes
1047 will be necessary only if packages are added to or removed from the
1048 configuration. For component writers, the build system should detect
1049 changes to the master copy of the header file source code and update
1050 the installed copies automatically during the next build. The build
1051 system is expected to perform a header file dependency analysis, so
1052 any source files affected should get rebuilt as well.
1057 Some build systems may provide additional support for application
1058 developers who want to make minor changes to a package, especially for
1059 debugging purposes. A header file could be copied from the
1060 component repository (which for application developers is assumed to
1061 be a read-only resource) into the build tree and edited there. The
1062 build system would detect a more recent version of such a header file
1063 in the build tree and install it. Care would have to be taken to
1064 recover properly if the modified copy in the build tree is
1065 subsequently removed, in order to revert to the original behaviour.
1070 When updating the install tree's <filename
1071 class="directory">include</filename> subdirectory, the build tree may
1072 also perform a clean-up operation. Specifically, it may check for any
1073 files which do not correspond to known exported header files and
1080 At present there is no defined support in the build system for
1081 defining custom build steps that generate exported header files. Any
1082 attempt to use the existing custom build step support may fall foul of
1083 unexpected header files being deleted automatically by the build
1084 system. This limitation will be addressed in a future release of the
1085 component framework, and may require changing the priority for
1086 exporting header files so that a custom build step can happen first.
1092 <!-- {{{ Compiling -->
1094 <sect2 id="build.make.compiles">
1095 <title>Compiling</title>
1098 Once there are up to date copies of all the exported header files in
1099 the build tree, the main build can proceed. Most of this involves
1100 compiling source files listed in &compile; properties in the &CDL;
1101 scripts for the various packages, for example:
1103 <programlisting width=72>
1104 cdl_package CYGPKG_ERROR {
1105 display "Common error code support"
1106 compile strerror.cxx
1111 &compile; properties may appear in the body of a &cdl-package;,
1112 &cdl-component;, &cdl-option; or &cdl-interface;. If the option or
1113 other &CDL; entity is active and enabled, the property takes effect.
1114 If the option is inactive or disabled the property is ignored. It is
1115 possible for a &compile; property to list multiple source files, and
1116 it is also possible for a given &CDL; entity to contain multiple
1117 &compile; properties. The following three examples are equivalent:
1119 <programlisting width=72>
1120 cdl_option <some_option> {
1122 compile file1.c file2.c file3.c
1125 cdl_option <some_option> {
1132 cdl_option <some_option> {
1134 compile file1.c file2.c
1139 Packages that follow the directory layout conventions should have a
1140 subdirectory <filename class="directory">src</filename>, and the
1141 component framework will first look for the specified files there.
1142 Failing that it will look for the specified files relative to the
1143 package's root directory. For example if a package contains a source
1144 file <filename>strerror.cxx</filename> then the following two lines
1147 <programlisting width=72>
1148 compile strerror.cxx
1149 compile src/strerror.cxx
1152 In the first case the component framework will find the file
1153 immediately in the packages <filename class="directory">src</filename>
1154 subdirectory. In the second case the framework will first look for a
1155 file <filename>src/src/strerror.cxx</filename>, and then for
1156 <filename>str/strerror.cxx</filename> relative to the package's root
1157 directory. The result is the same.
1160 The file names may be relative paths, allowing the source code to be
1161 split over multiple directories. For example if a package contains a
1162 file <filename>src/sync/mutex.cxx</filename> then the corresponding
1163 &CDL; entry would be:
1165 <programlisting width=72>
1166 compile sync/mutex.cxx
1169 All the source files relevant to the current configuration will be
1170 identified when the build tree is generated or updated, and added to
1171 the appropriate makefile (or its equivalent for other build systems).
1172 The actual build will involve a rule of the form:
1174 <programlisting width=72>
1175 <object file> : <source file>
1176 $(CC) -c $(INCLUDE_PATH) $(CFLAGS) -o $@ $<
1180 The component framework has built-in knowledge for processing source
1181 files written in C, C++ or assembler. These should have a
1182 <literal>.c</literal>, <literal>.cxx</literal> and
1183 <literal>.S</literal> suffix respectively. The current implementation
1184 has no simple mechanism for extending this with support for other
1185 languages or for alternative suffixes, but this should be addressed in
1189 The compiler command that will be used is something like
1190 <literal>arm-elf-gcc</literal>. This consists of a command prefix, in
1191 this case <literal>arm-elf</literal>, and a specific command such as
1192 <literal>gcc</literal>. The command prefix will depend on the target
1193 architecture and is controlled by a configuration option in the
1194 appropriate HAL package. It will have a sensible default value for the
1195 current architecture, but users can modify this option when necessary.
1196 The command prefix cannot be changed on a per-package basis, since
1197 it is usually essential that all packages are built with a consistent
1201 The <literal>$(INCLUDE_PATH)</literal> header file search path
1202 consists of at least the following:
1207 The <filename class="directory">include</filename> directory in the
1208 install tree. This allows source files to access the various header
1209 files exported by all the packages in the configuration, and also the
1210 configuration header files.
1215 The current package's root directory. This ensures that all files in
1216 the package are accessible at build time.
1221 The current package's <filename class="directory">src</filename>
1222 subdirectory, if it is present. Generally all files to be compiled are
1223 located in or below this directory. Typically this is used to access
1224 private header files containing implementation details only.
1229 The compiler flags <literal>$(CFLAGS)</literal> are determined in two
1230 steps. First the appropriate HAL package will provide a configuration
1231 option defining the global flags. Typically this includes flags that
1232 are needed for the target processor, for example
1233 <literal>-mcpu=arm9</literal>, various flags related to warnings,
1234 debugging and optimization, and flags such as
1235 <literal>-finit-priority</literal> which are needed by &eCos; itself.
1236 Users can modify the global flags option as required. In addition it
1237 is possible for existing flags to be removed from and new flags to be
1238 added to the current set on a per-package basis, again by means of
1239 user-modifiable configuration options. More details are given below.
1242 Component writers can assume that the build system will perform full
1243 header file dependency analysis, including dependencies on
1244 configuration headers, but the exact means by which this happens is
1245 implementation-defined. Typical application developers are unlikely to
1246 modify exported or private header files, but configuration headers are
1247 likely to change as the configuration is changed to better meet the
1248 needs of the application. Full header file dependency analysis also
1249 makes things easier for the component writers themselves.
1252 The current directory used during a compilation is an implementation
1253 detail of the build system. However it can be assumed that each
1254 package will have its own directory somewhere in the build tree, to
1255 prevent file name clashes, that this will be the current directory,
1256 and that intermediate object files will end up here.
1262 <!-- {{{ Library Generation -->
1264 <sect2 id="build.make.libraries">
1265 <title>Generating the Libraries</title>
1268 Once all the &compile; and &make-object; properties have been
1269 processed and the required object files have been built or rebuilt,
1270 these can be collected together in one or more libraries. The archiver
1271 will be the <application class="software">ar</application> command
1272 corresponding to the current architecture, for example <application
1273 class="software">powerpc-eabi-ar</application>. By default al of the
1274 object files will end up in a single library
1275 <filename>libtarget.a</filename>. This can be changed on a per-package
1276 basis using the <link linkend="ref.library">&library</link> property
1277 in the body of the corresponding &cdl-package; command, for example:
1279 <programlisting width=72>
1280 cdl_package <SOME_PACKAGE> {
1282 library libSomePackage.a
1287 However using different libraries for each package should be avoided.
1288 It makes things more difficult for application developers since they
1289 now have to link the application code with more libraries, and
1290 possibly even change this set of libraries when packages are added to
1291 or removed from the configuration. The use of a single library
1292 <filename>libtarget.a</filename> avoids any complications.
1295 It is also possible to change the target library for individual files,
1296 using a <literal>-library</literal> option with the corresponding
1297 &compile; or &make-object; property. For example:
1299 <programlisting width=72>
1300 compile -library=libSomePackage.a hello.c
1301 make_object -library=libSomePackage.a {
1306 Again this should be avoided because it makes application development
1307 more difficult. There is one special library which can be used freely,
1308 <filename>libextras.a</filename>, which is used to generate the
1309 <filename>extras.o</filename> file as described below.
1312 The order in which object files end up in a library is not defined.
1313 Typically each library will be created directly in the install tree,
1314 since there is little point in generating a file in the build tree and
1315 then immediately copying it to the install tree.
1321 <!-- {{{ extras.o -->
1323 <sect2 id="build.extras">
1324 <title>The <filename>extras.o</filename> file</title>
1327 Package sources files normally get compiled and then added to a
1328 library, by default <filename>libtarget.a</filename>, which is then
1329 linked with the application code. Because of the usual rules for
1330 linking with libraries, augmented by the use of link-time garbage
1331 collection, this means that code will only end up in the final
1332 executable if there is a direct or indirect reference to it in the
1333 application. Usually this is the desired behaviour: if the application
1334 does not make any use of say kernel message boxes, directly or
1335 indirectly, then that code should not end up in the final executable
1336 taking up valuable memory space.
1339 In a few cases it is desirable for package code to end up in the final
1340 executable even if there are no direct or indirect references. For
1341 example, device driver functions are often not called directly.
1342 Instead the application will access the device via the string
1343 <literal>"/dev/xyzzy"</literal> and call the device functions
1344 indirectly. This will be impossible if the functions have been
1345 removed at link-time.
1348 Another example involves static C++ objects. It is possible to have a
1349 static C++ object, preferably with a suitable constructor priority,
1350 where all of the interesting work happens as a side effect of running
1351 the constructor. For example a package might include a monitoring
1352 thread or a garbage collection thread created from inside such a
1353 constructor. Without a reference by the application to the static
1354 object the latter will never get linked in, and the package will not
1355 function as expected.
1358 A third example would be copyright messages. A package vendor may want
1359 to insist that all products shipped using that package include a
1360 particular message in memory, even though many users of that package
1361 will object to such a restriction.
1364 To meet requirements such as these the build system provides support
1365 for a file <filename>extras.o</filename>, which always gets linked
1366 with the application code via the linker script. Because it is an
1367 object file rather than a library everything in the file will be
1368 linked in. The <filename>extras.o</filename> file is generated at the
1369 end of a build from a library <filename>libextras.a</filename>, so
1370 packages can put functions and variables in suitable source files and
1371 add them to that library explicitly:
1373 <programlisting width=72>
1374 compile -library=libextras.a xyzzy.c
1375 compile xyzzy_support.c
1378 In this example <filename>xyzzy.o</filename> will end up in
1379 <filename>libextras.a</filename>, and hence in
1380 <filename>extras.o</filename> and in the final executable.
1381 <filename>xyzzy_support.o</filename> will end up in
1382 <filename>libtarget.a</filename> as usual, and is subject to linker
1389 <!-- {{{ Compilers and flags -->
1391 <sect2 id="build.flags">
1392 <title>Compilers and Flags</title>
1396 Some of the details of compiler selection and compiler flags described
1397 below are subject to change in future revisions of the component
1398 framework, although every reasonable attempt will be made to avoid
1399 breaking backwards compatibility.
1404 The build system needs to know what compiler to use, what compiler
1405 flags should be used for different stages of the build and so on. Much
1406 of this information will vary from target to target, although users
1407 should be able to override this when appropriate. There may also be a
1408 need for some packages to modify the compiler flags. All platform HAL
1409 packages should define a number of options with well-known names,
1410 along the following lines (any existing platform HAL package can be
1411 consulted for a complete example):
1413 <programlisting width=72>
1414 cdl_component CYGBLD_GLOBAL_OPTIONS {
1419 cdl_option CYGBLD_GLOBAL_COMMAND_PREFIX {
1421 default_value { "arm-elf" }
1424 cdl_option CYGBLD_GLOBAL_CFLAGS {
1426 default_value "-Wall -g -O2 …"
1430 cdl_option CYGBLD_GLOBAL_LDFLAGS {
1432 default_value "-g -nostdlib -Wl,--gc-sections …"
1438 The <varname>CYGBLD_GLOBAL_OPTIONS</varname> component serves to
1439 collect together all global build-related options. It has the flavor
1440 <literal>none</literal> since disabling all of these options would
1441 make it impossible to build anything and hence is not useful. It is
1442 parented immediately below the root of the configuration hierarchy,
1443 thus making sure that it is readily accessible in the graphical
1444 configuration tool and, for command line users, in the
1445 <filename>ecos.ecc</filename> save file.
1449 Currently the &parent; property lists a parent of
1450 <varname>CYGPKG_NONE</varname>, rather than an empty string. This
1451 could be unfortunate if there was ever a package with that name. The
1452 issue will be addressed in a future release of the component
1457 The option <varname>CYGBLD_GLOBAL_COMMAND_PREFIX</varname> defines
1458 which tools should be used for the current target. Typically this is
1459 determined by the processor on the target hardware. In some cases a
1460 given target board may be able to support several different
1461 processors, in which case the &default-value; expression could select
1462 a different toolchain depending on some other option that is used to
1463 control which particular processor.
1464 <varname>CYGBLD_GLOBAL_COMMAND_PREFIX</varname> is modifiable rather
1465 than calculated, so users can override this when necessary.
1468 Given a command prefix such as <literal>arm-elf</literal>, all C
1469 source files will be compiled with <literal>arm-elf-gcc</literal>, all
1470 C++ sources will be built using <literal>arm-elf-g++</literal>,
1471 and <literal>arm-elf-ar</literal> will be used to generate the
1472 library. This is in accordance with the usual naming conventions for
1473 GNU cross-compilers and similar tools. For the purposes of custom
1474 build steps, tokens such as <literal>$(CC)</literal> will be set to
1475 <literal>arm-elf-gcc</literal>.
1478 The next option, <varname>CYGBLD_GLOBAL_CFLAGS</varname>, is used to
1479 provide the initial value of <literal>$(CFLAGS)</literal>. Some
1480 compiler flags such as <literal>-Wall</literal> and
1481 <literal>-g</literal> are likely to be used on all targets. Other
1482 flags such as <literal>-mcpu=arm7tdmi</literal> will be
1483 target-specific. Again this is a modifiable option, so the user can
1484 switch from say <literal>-O2</literal> to <literal>-Os</literal> if
1485 desired. The option <varname>CYGBLD_GLOBAL_LDFLAGS</varname> serves
1486 the same purpose for <literal>$(LDFLAGS)</literal> and linking. It is
1487 used primarily when building test cases or possibly for some custom
1488 build steps, since building eCos itself generally involves building
1489 one or more libraries rather than executables.
1492 Some packages may wish to add certain flags to the global set, or
1493 possibly remove some flags. This can be achieved by having
1494 appropriately named options in the package, for example:
1496 <programlisting width=72>
1497 cdl_component CYGPKG_KERNEL_OPTIONS {
1498 display "Kernel build options"
1502 cdl_option CYGPKG_KERNEL_CFLAGS_ADD {
1503 display "Additional compiler flags"
1505 default_value { "" }
1509 cdl_option CYGPKG_KERNEL_CFLAGS_REMOVE {
1510 display "Suppressed compiler flags"
1512 default_value { "" }
1516 cdl_option CYGPKG_KERNEL_LDFLAGS_ADD {
1517 display "Additional linker flags"
1519 default_value { "" }
1523 cdl_option CYGPKG_KERNEL_LDFLAGS_REMOVE {
1524 display "Suppressed linker flags"
1526 default_value { "" }
1532 In this example the kernel does not modify the global compiler flags
1533 by default, but it is possible for the users to modify the options if
1534 desired. The value of <literal>$(CFLAGS)</literal> that is used for
1535 the compilations and custom build steps in a given package is
1536 determined as follows:
1541 Start with the global settings from
1542 <varname>CYGBLD_GLOBAL_CFLAGS</varname>, for example
1543 <literal>-g -O2</literal>.
1548 Remove any flags specified in the per-package
1549 <literal>CFLAGS_REMOVE</literal> option, if any. For example
1550 if <literal>-O2</literal> should be removed for this package then
1551 <literal>$(CFLAGS)</literal> would now have a value of just
1552 <literal>-g</literal>.
1557 Then concatenate the flags specified by the per-package
1558 <literal>CFLAGS_ADD</literal> option, if any. For example if
1559 <literal>-Os</literal> should be added for the current package then
1560 the final value of <literal>$(CFLAGS)</literal> will be
1561 <literal>-g -Os</literal>.
1566 <literal>$(LDFLAGS)</literal> is determined in much the same way.
1571 The way compiler flags are handled at present has numerous limitations
1572 that need to be addressed in a future release, although it should
1573 suffice for nearly all cases. For the time being custom build steps
1574 and in particular the &make-object; property can be used to work
1575 around the limitations.
1578 Amongst the issues, there is a specific problem with package
1579 encapsulation. For example the math library imposes some stringent
1580 requirements on the compiler in order to guarantee exact IEEE
1581 behavior, and may need special flags on a per-architecture basis. One
1582 way of handling this is to have
1583 <varname>CYGPKG_LIBM_CFLAGS_ADD</varname> and
1584 <varname>CYGPKG_LIBM_CFLAGS_REMOVE</varname> &default-value;
1585 expressions which depend on the target architecture, but such
1586 expressions may have to updated for each new architecture. An
1587 alternative approach would allow the architectural HAL package to
1588 modify the &default-value; expressions for the math library, but this
1589 breaks encapsulation. A third approach would allow some architectural
1590 HAL packages to define one or more special options with well-known
1591 names, and the math library could check if these options were defined
1592 and adjust the default values appropriately. Other packages with
1593 floating point requirements could do the same. This approach also has
1594 scalability issues, in particular how many such categories of options
1595 would be needed? It is not yet clear how best to resolve such issues.
1601 When generating a build tree it would be desirable for the component
1602 framework to output details of the tools and compiler flags in a
1603 format that can be re-used for application builds, for example a
1604 makefile fragment. This would make it easier for application
1605 developers to use the same set of flags as were used for building eCos
1606 itself, thus avoiding some potential problems with incompatible
1614 <!-- {{{ Custom build steps -->
1616 <sect2 id="build.custom">
1617 <title>Custom Build Steps</title>
1621 Some of the details of custom build steps as described below are
1622 subject to change in future revisions of the component framework,
1623 although every reasonable attempt will be made to avoid breaking
1624 backwards compatibility.
1629 For most packages simply listing one or more source files in a
1630 &compile; property is sufficient. These files will get built using the
1631 appropriate compiler and compiler flags and added to a library, which
1632 then gets linked with application code. A package that can be built in
1633 this way is likely to be more portable to different targets and build
1634 environments, since it avoids build-time dependencies. However some
1635 packages have special needs, and the component framework supports
1636 custom build steps to allow for these needs. There are two properties
1637 related to this, &make; and &make-object;, and both take the following
1640 <programlisting width=72>
1642 <target_filepath> : <dependency_filepath> …
1648 Although this may look like makefile syntax, and although some build
1649 environments will indeed involve generating makefiles and running
1650 <application class="software">make</application>, this is not
1651 guaranteed. It is possible for the component framework to be
1652 integrated with some other build system, and custom build steps should
1653 be written with that possibility in mind. Each custom build step
1654 involves a target, some number of dependency files, and some number of
1655 commands. If the target is not up to date with respect to one or more
1656 of the dependencies then the commands need to be executed.
1659 <orderedlist numeration="Loweralpha">
1663 Only one target can be specified. For a &make-object; property this
1664 target must be an object file. For a &make; property it can be any
1665 file. In both cases it must refer to a physical file, the use of
1666 phony targets is not supported. The target should not be an absolute
1667 path name. If the generated file needs to end up in the install tree
1668 then this can be achieved using a <literal><PREFIX></literal>
1671 <programlisting width=72>
1673 <PREFIX>/lib/mytarget : …
1678 When the build tree is generated and the custom build step is added to
1679 the makefile (or whatever build system is used)
1680 <literal><PREFIX></literal> will be replaced with the absolute
1681 path to the install tree.
1687 All the dependencies must also refer to physical files, not to phony
1688 targets. These files may be in the source tree. The
1689 <literal><PACKAGE></literal> token can be used to indicate this:
1690 when the build tree is generated this token will be replaced with the
1691 absolute path to the package's root directory in the component
1692 repository, for example:
1694 <programlisting width=72>
1696 xyzzy.o : <PACKAGE>/src/xyzzy.c
1700 If the component repository was installed in <filename
1701 class="directory">/usr/local/ecos</filename> and this custom build
1702 step existed in version 1_5 of the kernel,
1703 <literal><PACKAGE></literal> would be replaced with
1704 <filename>/usr/local/ecos/packages/kernel/v1_5</filename>.
1707 Alternatively the dependencies may refer to files that are generated
1708 during the build. These may be object files resulting from &compile;
1709 properties or other &make-object; properties, or they may be other
1710 files resulting from a &make; property, for example:
1712 <programlisting width=72>
1722 No other token or makefile variables may be used in the target or
1723 dependency file names. Also conditionals such as
1724 <literal>ifneq</literal> and similar makefile functionality must not
1731 Similarly the list of commands must not use any makefile conditionals
1732 or similar functionality. A number of tokens can be used to provide
1733 access to target-specific or environmental data. Note that these
1734 tokens look like makefile variables, unlike the
1735 <literal><PREFIX></literal> and
1736 <literal><PACKAGE></literal> tokens mentioned earlier:
1739 <informaltable frame="all" colsep=1 rowsep=1 pgwide=0 tocentry=0>
1740 <tgroup cols=3 colsep=1 rowsep=1 align=left>
1743 <entry>Token</entry>
1744 <entry>Purpose</entry>
1745 <entry>Example value</entry>
1750 <entry><literal>$(AR)</literal></entry>
1751 <entry>the GNU archiver</entry>
1752 <entry><literal>mips-tx39-elf-ar</literal></entry>
1755 <entry><literal>$(CC)</literal></entry>
1756 <entry>the GNU compiler</entry>
1757 <entry><literal>sh-elf-gcc</literal></entry>
1760 <entry><literal>$(CFLAGS)</literal></entry>
1761 <entry>compiler flags</entry>
1762 <entry><literal>-O2 -Wall</literal></entry>
1765 <entry><literal>$(COMMAND_PREFIX)</literal></entry>
1766 <entry>the triplet prefix</entry>
1767 <entry><literal>mn10300-elf-</literal></entry>
1770 <entry><literal>$(INCLUDE_PATH></literal></entry>
1771 <entry>header file search path</entry>
1772 <entry><literal>-I. -Isrc/misc</literal></entry>
1775 <entry><literal>$(LDFLAGS)</literal></entry>
1776 <entry>linker flags</entry>
1777 <entry><literal>-nostdlib -Wl,-static</literal></entry>
1780 <entry><literal>$(OBJCOPY)</literal></entry>
1781 <entry>the objcopy utility</entry>
1782 <entry><literal>arm-elf-objcopy</literal></entry>
1785 <entry><literal>$(PREFIX)</literal></entry>
1786 <entry>location of the install tree</entry>
1787 <entry><filename class="directory">/home/fred/ecos-install</filename></entry>
1790 <entry><literal>$(REPOSITORY)</literal></entry>
1791 <entry>location of the component repository</entry>
1792 <entry><filename class="directory">/home/fred/ecos/packages</filename></entry>
1799 In addition commands in a custom build step may refer to the target
1800 and the dependencies using <literal>$@</literal>,
1801 <literal>$<</literal>, <literal>$^</literal> and
1802 <literal>$*</literal>, all of which behave as per GNU make syntax. The
1803 commands will execute in a suitable directory in the build tree.
1809 The current directory used during a custom build step is an
1810 implementation detail of the build system. However it can be assumed
1811 that each package will have its own directory somewhere in the build
1812 tree, to prevent file name clashes, and that this will be the current
1813 directory. In addition any object files generated as a result of
1814 &compile properties will be located here as well, which is useful for
1815 custom build steps that depend on a <literal>.o</literal> file
1816 previously generated.
1819 Any temporary files created by a custom build step should be generated
1820 in the build tree (in or under the current directory). Such files
1821 should be given a <filename>.tmp</filename> file extension to ensure
1822 that they are deleted during a <literal>make clean</literal> or
1823 equivalent operation.
1826 If a package contains multiple custom build steps with the same
1827 priority, it is possible that these build steps will be run
1828 concurrently. Therefore these custom build steps must not accidentally
1829 use the same file names for intermediate files.
1835 Care has to be taken to make sure that the commands in a custom build
1836 step will run on all host platforms, including Windows NT as well as
1837 Linux and other Unix systems. For example, all file paths should use
1838 forward slashes as the directory separator. It can be assumed that
1839 Windows users will have a full set of CygWin tools installed and
1840 available on the path. The <ulink
1841 url="http://www.gnu.org/prep/standards.html">GNU coding
1842 standards</ulink> provide some useful guidelines for writing portable
1849 A custom build step must not make any assumptions concerning the
1850 version of another package. This enforces package encapsulation,
1851 preventing one package from accessing the internals of another.
1857 No assumptions should be made about the target platform, unless the
1858 package is inherently specific to that platform. Even then it is
1859 better to use the various tokens whenever possible, rather than
1860 hard-coding in details such as the compiler. For example, given a
1861 custom build step such as:
1863 <programlisting width=72>
1864 arm-elf-gcc -c -mcpu=arm7di -o $@ $<
1867 Even if this build step will only be invoked on ARM targets, it could
1868 cause problems. For example the toolchain may have been installed
1869 using a prefix other than <literal>arm-elf</literal>. Also, if the
1870 user changes the compiler flags then this would not be reflected in
1871 the build step. The correct way to write this rule would be:
1873 <programlisting width=72>
1874 $(CC) -c $(CFLAGS) -o $@ $<
1877 Some commands such as the compiler, the archiver, and objcopy are
1878 required sufficiently often to warrant their own tokens, for example
1879 <literal>$(CC)</literal> and <literal>$(OBJCOPY)</literal>. Other
1880 target-specific commands are needed only rarely and the
1881 <literal>$(COMMAND_PREFIX)</literal> token can be used to construct
1882 the appropriate command name, for example:
1884 <programlisting width=72>
1886 $(COMMAND_PREFIX)size $< > $@
1892 Custom build steps should not be used to build host-side executables,
1893 even if those executables are needed to build parts of the target side
1894 code. Support for building host-side executables will be added in a
1895 future version of the component framework, although it will not
1896 necessarily involve these custom build steps.
1903 By default custom build steps defined in a &make-object; property
1904 have a priority of 100, which means that they will be executed
1905 in the same phase as compilations resulting from a &compile; property.
1906 It is possible to change the priority using a property option, for
1909 <programlisting width=72>
1910 make_object -priority 50 {
1915 Specifying a priority smaller than a 100 means that the custom build
1916 step happens before the normal compilations. Priorities between 100
1917 and 200 happen after normal compilations but before the libraries are
1918 archived together. &make-object; properties should not specify a
1919 priority of 200 or later.
1922 Custom build steps defined in a &make; property have a default
1923 priority of 300, and so they will happen after the libraries have been
1924 built. Again this can be changed using a <literal>-priority</literal>
1931 <!-- {{{ Startup Code -->
1933 <sect2 id="build.startup">
1934 <title>Startup Code</title>
1937 Linking an application requires the application code, a linker script,
1938 the eCos library or libraries, the <literal>extras.o</literal> file,
1939 and some startup code. Depending on the target hardware and how the
1940 application gets booted, this startup code may do little more than
1941 branching to <literal>main()</literal>, or it may have to perform a
1942 considerable amount of hardware initialization. The startup code
1943 generally lives in a file <literal>vectors.o</literal> which is
1944 created by a custom build step in a HAL package. As far as application
1945 developers are concered the existence of this file is largely
1946 transparent, since the linker script ensures that the file is part of
1947 the final executable.
1950 This startup code is not generally of interest to component writers,
1951 only to HAL developers who are referred to one of the existing HAL
1952 packages for specific details. Other packages are not expected to
1953 modify the startup in any way. If a package needs some work performed
1954 early on during system initialization, before the application's main
1955 entry point gets invoked, this can be achieved using a static object
1956 with a suitable constructor priority.
1961 It is possible that the <literal>extras.o</literal> support, in
1962 conjunction with appropriate linker script directives, could be used
1963 to eliminate the need for a special startup file. The details are not
1971 <!-- {{{ The Linker Script -->
1973 <sect2 id="build.linkerscript">
1974 <title>The Linker Script</title>
1978 This section is not finished, and the details are subject to change in
1979 a future release. Arguably linker script issues should be documented
1980 in the HAL documentation rather than in this guide.
1985 Generating the linker script is the responsibility of the various HAL
1986 packages that are applicable to a given target. Developers of
1987 components other than HAL packages need not be concerned about what is
1988 involved. Developers of new HAL packages should use an existing HAL as
1994 It may be desirable for some packages to have some control over the
1995 linker script, for example to add extra alignment details for a
1996 particular section. This can be risky because it can result in subtle
1997 portability problems, and the current component framework has no
1998 support for any such operations. The issue may be addressed in a
2010 <!-- {{{ Test cases -->
2012 <sect1 id="build.tests">
2013 <title>Building Test Cases</title>
2017 The support in the current implementation of the component framework
2018 for building and running test cases is limited, and should be enhanced
2019 considerably in a future version. Compatibility with the existing
2020 mechanisms described below will be maintained if possible, but this
2021 cannot be guaranteed.
2026 Whenever possible packages should be shipped with one or more test
2027 cases. This allows users to check that all packages function correctly
2028 in their particular configuration and on their target, which may be
2029 custom hardware unavailable to the package developer. The component
2030 framework needs to provide a way of building such test cases. For
2031 example, if a makefile system is used then there could be a
2032 <literal>make tests</literal> target to build the test cases, or
2033 possibly a <literal>make check</literal> target to build and run
2034 the test cases and process all the results. Unfortunately there are
2035 various complications.
2038 Not every test case will be applicable to every configuration. For
2039 example if the user has disabled the C library's
2040 <varname>CYGPKG_LIBC_STDIO</varname> component then there is no point
2041 in building or running any of the test cases for that component. This
2042 implies that test cases need to be associated with configuration
2043 options somehow. It is possible for the test case to use one or more
2044 <literal>#ifdef</literal> statements to check whether or not it is
2045 applicable in the current configuration, and compile to a null program
2046 when not applicable. This is inefficient because the test case will
2047 still get built and possibly run, even though it will not provide any
2051 Many packages involve direct interaction with hardware, for example a
2052 serial line or an ethernet interface. In such cases it is only
2053 worthwhile building and running the test if there is suitable software
2054 running at the other end of the serial line or listening on the same
2055 ethernet segment, and that software would typically have to run on the
2056 host. Of course the serial line in question may be hooked up to a
2057 different piece of hardware which the application needs to talk to, so
2058 disconnecting it and then hooking it up to the host for running some
2059 tests may be undesirable. The decision as to whether or not to build
2060 the test depends not just on the eCos configuration but also on the
2061 hardware setup and the availability of suitable host software.
2064 There are different kinds of tests, and it is not always desirable to
2065 run all of them. For example a package may contain a number of stress
2066 tests intended to run for long periods of time, possibly days or
2067 longer. Such tests should certainly be distinguished somehow from
2068 ordinary test cases so that users will not run them accidentally and
2069 wonder how long they should wait for a <literal>pass</literal> message
2070 before giving up. Stress tests may also have dependencies on the
2071 hardware configuration and on host software, for example a network
2072 stress test may require lots of ethernet packets.
2075 In the current implementation of the component framework these issues
2076 are not yet addressed. Instead there is only very limited support for
2077 building test cases. Any package can define a calculated configuration
2079 <literal>CYGPKG_<package-name>_TESTS</literal>, whose value is a
2080 list of test cases. The &calculated; property can involve an
2081 expression so it is possible to adapt to a small number of
2082 configuration options, but this quickly becomes unwieldy. A typical
2085 <programlisting width=80>
2086 cdl_option CYGPKG_UITRON_TESTS {
2087 display "uITRON tests"
2090 calculated { "tests/test1 tests/test2 tests/test3 \
2091 tests/test4 tests/test5 tests/test6 tests/test7 \
2092 tests/test8 tests/test9 tests/testcxx tests/testcx2 \
2093 tests/testcx3 tests/testcx4 tests/testcx5 \
2094 tests/testcx6 tests/testcx7 tests/testcx8 \
2095 tests/testcx9 tests/testintr" }
2097 This option specifies the set of tests for the uITRON compatibility layer."
2102 This implies that there is a file <filename>tests/test1.c</filename>
2103 or <filename>tests/test1.cxx</filename> in the package's directory.
2104 The commands that will be used to build the test case will take the
2107 <programlisting width=72>
2108 $(CC) -c $(INCLUDE_PATH) $(CFLAGS) -o <build path>/test1.o \
2109 <source path>/tests/test1.c
2110 $(CC) $(LDFLAGS) -o <install path>/tests/test1 <build_path>/test1.o
2113 The variables <literal>$(CC)</literal> and so on are determined in the
2114 same way as for custom build steps. The various paths and the current
2115 directory will depend on the exact build system being used, and are
2116 subject to change. As usual the sources in the component repository
2117 are treated as a read-only resources, intermediate files live in the
2118 build tree, and the desired executables should end up in the install
2122 Each test source file must be self-contained. It is not possible at
2123 present to build a little per-package library that can be used by the
2124 test cases, or to link together several object files to produce a
2125 single test executable. In some cases it may be possible to
2126 <literal>#include</literal> source code from a shared file in order to
2127 avoid unnecessary code replication. There is no support for
2128 manipulating compiler or linker flags for individual test cases: the
2129 flags that will be used for all files are <literal>$(CFLAGS)</literal>
2130 and <literal>$(LDFLAGS)</literal>, as per custom build steps. Note
2131 that it is possible for a package to define options of the form
2132 <varname>CYGPKG_<PACKAGE-NAME>_LDFLAGS_ADD</varname> and
2133 <varname>CYGPKG_<PACKAGE-NAME>_LDFLAGS_REMOVE</varname>. These
2134 will affect test cases, but in the absence of custom build steps they
2135 will have no other effect on the build.