delete them.</P
></LI
></OL
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>At present there is no defined support in the build system for
defining custom build steps that generate exported header files. Any
attempt to use the existing custom build step support may fall foul of
unexpected header files being deleted automatically by the build
system. This limitation will be addressed in a future release of the
component framework, and may require changing the priority for
exporting header files so that a custom build step can happen first.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="BUILD.MAKE.COMPILES">Compiling</H2
><P
>Once there are up to date copies of all the exported header files in
the build tree, the main build can proceed. Most of this involves
compiling source files listed in <SPAN
CLASS="PROPERTY"
>compile</SPAN
> properties in the <SPAN
CLASS="APPLICATION"
>CDL</SPAN
>
scripts for the various packages, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_package CYGPKG_ERROR {
    display       "Common error code support"
    compile       strerror.cxx
    &#8230;
}</PRE
></TD
></TR
></TABLE
><P
><SPAN
CLASS="PROPERTY"
>compile</SPAN
> properties may appear in the body of a <TT
CLASS="LITERAL"
>cdl_package</TT
>,
<TT
CLASS="LITERAL"
>cdl_component</TT
>, <TT
CLASS="LITERAL"
>cdl_option</TT
> or <TT
CLASS="LITERAL"
>cdl_interface</TT
>. If the option or
other <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> entity is active and enabled, the property takes effect.
If the option is inactive or disabled the property is ignored. It is
possible for a <SPAN
CLASS="PROPERTY"
>compile</SPAN
> property to list multiple source files, and
it is also possible for a given <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> entity to contain multiple
<SPAN
CLASS="PROPERTY"
>compile</SPAN
> properties. The following three examples are equivalent:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_option &lt;some_option&gt; {
    &#8230;
    compile file1.c file2.c file3.c
}

cdl_option &lt;some_option&gt; {
    &#8230;
    compile file1.c
    compile file2.c
    compile file3.c
}

cdl_option &lt;some_option&gt; {
    &#8230;
    compile file1.c file2.c
    compile file3.c
}</PRE
></TD
></TR
></TABLE
><P
>Packages that follow the directory layout conventions should have a
subdirectory <TT
CLASS="FILENAME"
>src</TT
>, and the
component framework will first look for the specified files there.
Failing that it will look for the specified files relative to the
package's root directory. For example if a package contains a source
file <TT
CLASS="FILENAME"
>strerror.cxx</TT
> then the following two lines
are equivalent:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    compile strerror.cxx
    compile src/strerror.cxx</PRE
></TD
></TR
></TABLE
><P
>In the first case the component framework will find the file
immediately in the packages <TT
CLASS="FILENAME"
>src</TT
>
subdirectory. In the second case the framework will first look for a
file <TT
CLASS="FILENAME"
>src/src/strerror.cxx</TT
>, and then for
<TT
CLASS="FILENAME"
>str/strerror.cxx</TT
> relative to the package's root
directory. The result is the same.</P
><P
>The file names may be relative paths, allowing the source code to be
split over multiple directories. For example if a package contains a
file <TT
CLASS="FILENAME"
>src/sync/mutex.cxx</TT
> then the corresponding
<SPAN
CLASS="APPLICATION"
>CDL</SPAN
> entry would be:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    compile sync/mutex.cxx</PRE
></TD
></TR
></TABLE
><P
>All the source files relevant to the current configuration will be
identified when the build tree is generated or updated, and added to
the appropriate makefile (or its equivalent for other build systems).
The actual build will involve a rule of the form:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>&lt;object file&gt; : &lt;source file&gt;
        $(CC) -c $(INCLUDE_PATH) $(CFLAGS) -o $@ $&#60;</PRE
></TD
></TR
></TABLE
><P
>The component framework has built-in knowledge for processing source
files written in C, C++ or assembler. These should have a
<TT
CLASS="LITERAL"
>.c</TT
>, <TT
CLASS="LITERAL"
>.cxx</TT
> and
<TT
CLASS="LITERAL"
>.S</TT
> suffix respectively. The current implementation
has no simple mechanism for extending this with support for other
languages or for alternative suffixes, but this should be addressed in
a future release.</P
><P
>The compiler command that will be used is something like
<TT
CLASS="LITERAL"
>arm-elf-gcc</TT
>. This consists of a command prefix, in
this case <TT
CLASS="LITERAL"
>arm-elf</TT
>, and a specific command such as
<TT
CLASS="LITERAL"
>gcc</TT
>. The command prefix will depend on the target
architecture and is controlled by a configuration option in the
appropriate HAL package. It will have a sensible default value for the
current architecture, but users can modify this option when necessary.
The command prefix cannot be changed on a per-package basis, since
it is usually essential that all packages are built with a consistent
set of tools.</P
><P
>The <TT
CLASS="LITERAL"
>$(INCLUDE_PATH)</TT
> header file search path
consists of at least the following:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>The <TT
CLASS="FILENAME"
>include</TT
> directory in the
install tree. This allows source files to access the various header
files exported by all the packages in the configuration, and also the
configuration header files.</P
></LI
><LI
><P
>The current package's root directory. This ensures that all files in
the package are accessible at build time.</P
></LI
><LI
><P
>The current package's <TT
CLASS="FILENAME"
>src</TT
>
subdirectory, if it is present. Generally all files to be compiled are
located in or below this directory. Typically this is used to access
private header files containing implementation details only.</P
></LI
></OL
><P
>The compiler flags <TT
CLASS="LITERAL"
>$(CFLAGS)</TT
> are determined in two
steps. First the appropriate HAL package will provide a configuration
option defining the global flags. Typically this includes flags that
are needed for the target processor, for example
<TT
CLASS="LITERAL"
>-mcpu=arm9</TT
>, various flags related to warnings,
debugging and optimization, and flags such as
<TT
CLASS="LITERAL"
>-finit-priority</TT
> which are needed by <SPAN
CLASS="APPLICATION"
>eCos</SPAN
> itself.
Users can modify the global flags option as required. In addition it
is possible for existing flags to be removed from and new flags to be
added to the current set on a per-package basis, again by means of
user-modifiable configuration options. More details are given below.</P
><P
>Component writers can assume that the build system will perform full
header file dependency analysis, including dependencies on
configuration headers, but the exact means by which this happens is
implementation-defined. Typical application developers are unlikely to
modify exported or private header files, but configuration headers are
likely to change as the configuration is changed to better meet the
needs of the application. Full header file dependency analysis also
makes things easier for the component writers themselves.</P
><P
>The current directory used during a compilation is an implementation
detail of the build system. However it can be assumed that each
package will have its own directory somewhere in the build tree, to
prevent file name clashes, that this will be the current directory,
and that intermediate object files will end up here.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="BUILD.MAKE.LIBRARIES">Generating the Libraries</H2
><P
>Once all the <SPAN
CLASS="PROPERTY"
>compile</SPAN
> and <SPAN
CLASS="PROPERTY"
>make_object</SPAN
> properties have been
processed and the required object files have been built or rebuilt,
these can be collected together in one or more libraries. The archiver
will be the <SPAN
CLASS="APPLICATION"
>ar</SPAN
> command
corresponding to the current architecture, for example <SPAN
CLASS="APPLICATION"
>powerpc-eabi-ar</SPAN
>. By default al of the
object files will end up in a single library
<TT
CLASS="FILENAME"
>libtarget.a</TT
>. This can be changed on a per-package
basis using the <A
HREF="ref.library.html"
><SPAN
CLASS="PROPERTY"
>library</SPAN
></A
> property
in the body of the corresponding <TT
CLASS="LITERAL"
>cdl_package</TT
> command, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_package &lt;SOME_PACKAGE&gt; {
    &#8230;
    library  libSomePackage.a
}</PRE
></TD
></TR
></TABLE
><P
>However using different libraries for each package should be avoided.
It makes things more difficult for application developers since they
now have to link the application code with more libraries, and
possibly even change this set of libraries when packages are added to
or removed from the configuration. The use of a single library
<TT
CLASS="FILENAME"
>libtarget.a</TT
> avoids any complications.</P
><P
>It is also possible to change the target library for individual files,
using a <TT
CLASS="LITERAL"
>-library</TT
> option with the corresponding
<SPAN
CLASS="PROPERTY"
>compile</SPAN
> or <SPAN
CLASS="PROPERTY"
>make_object</SPAN
> property. For example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    compile -library=libSomePackage.a hello.c
    make_object -library=libSomePackage.a {
        &#8230;
    }</PRE
></TD
></TR
></TABLE
><P
>Again this should be avoided because it makes application development
more difficult. There is one special library which can be used freely,
<TT
CLASS="FILENAME"
>libextras.a</TT
>, which is used to generate the
<TT
CLASS="FILENAME"
>extras.o</TT
> file as described below.</P
><P
>The order in which object files end up in a library is not defined.
Typically each library will be created directly in the install tree,
since there is little point in generating a file in the build tree and
then immediately copying it to the install tree.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="BUILD.EXTRAS">The <TT
CLASS="FILENAME"
>extras.o</TT
> file</H2
><P
>Package sources files normally get compiled and then added to a
library, by default <TT
CLASS="FILENAME"
>libtarget.a</TT
>, which is then
linked with the application code. Because of the usual rules for
linking with libraries, augmented by the use of link-time garbage
collection, this means that code will only end up in the final
executable if there is a direct or indirect reference to it in the
application. Usually this is the desired behaviour: if the application
does not make any use of say kernel message boxes, directly or
indirectly, then that code should not end up in the final executable
taking up valuable memory space.</P
><P
>In a few cases it is desirable for package code to end up in the final
executable even if there are no direct or indirect references. For
example, device driver functions are often not called directly.
Instead the application will access the device via the string
<TT
CLASS="LITERAL"
>"/dev/xyzzy"</TT
> and call the device functions
indirectly. This will be impossible if the functions have been
removed at link-time.</P
><P
>Another example involves static C++ objects. It is possible to have a
static C++ object, preferably with a suitable constructor priority,
where all of the interesting work happens as a side effect of running
the constructor. For example a package might include a monitoring
thread or a garbage collection thread created from inside such a
constructor. Without a reference by the application to the static
object the latter will never get linked in, and the package will not
function as expected.</P
><P
>A third example would be copyright messages. A package vendor may want
to insist that all products shipped using that package include a
particular message in memory, even though many users of that package
will object to such a restriction.</P
><P
>To meet requirements such as these the build system provides support
for a file <TT
CLASS="FILENAME"
>extras.o</TT
>, which always gets linked
with the application code via the linker script. Because it is an
object file rather than a library everything in the file will be
linked in. The <TT
CLASS="FILENAME"
>extras.o</TT
> file is generated at the
end of a build from a library <TT
CLASS="FILENAME"
>libextras.a</TT
>, so
packages can put functions and variables in suitable source files and
add them to that library explicitly:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    compile -library=libextras.a xyzzy.c
    compile xyzzy_support.c</PRE
></TD
></TR
></TABLE
><P
>In this example <TT
CLASS="FILENAME"
>xyzzy.o</TT
> will end up in
<TT
CLASS="FILENAME"
>libextras.a</TT
>, and hence in
<TT
CLASS="FILENAME"
>extras.o</TT
> and in the final executable.
<TT
CLASS="FILENAME"
>xyzzy_support.o</TT
> will end up in
<TT
CLASS="FILENAME"
>libtarget.a</TT
> as usual, and is subject to linker
garbage collection.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="BUILD.FLAGS">Compilers and Flags</H2
><DIV
CLASS="CAUTION"
><P
></P
><TABLE
CLASS="CAUTION"
BORDER="1"
WIDTH="100%"
><TR
><TD
ALIGN="CENTER"
><B
>Caution</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
><P
>Some of the details of compiler selection and compiler flags described
below are subject to change in future revisions of the component
framework, although every reasonable attempt will be made to avoid
breaking backwards compatibility.</P
></TD
></TR
></TABLE
></DIV
><P
>The build system needs to know what compiler to use, what compiler
flags should be used for different stages of the build and so on. Much
of this information will vary from target to target, although users
should be able to override this when appropriate. There may also be a
need for some packages to modify the compiler flags. All platform HAL
packages should define a number of options with well-known names,
along the following lines (any existing platform HAL package can be
consulted for a complete example):</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"