URL
https://opencores.org/ocsvn/or1k_old/or1k_old/trunk
Subversion Repositories or1k_old
[/] [or1k_old/] [trunk/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [build.make.html] - Rev 1782
Compare with Previous | Blame | View Log
<!-- Copyright (C) 2003 Red Hat, Inc. -->
<!-- This material may be distributed only subject to the terms -->
<!-- and conditions set forth in the Open Publication License, v1.0 -->
<!-- or later (the latest version is presently available at -->
<!-- http://www.opencontent.org/openpub/). -->
<!-- Distribution of the work or derivative of the work in any -->
<!-- standard (paper) book form is prohibited unless prior -->
<!-- permission is obtained from the copyright holder. -->
<HTML
><HEAD
><TITLE
>Building eCos</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="The eCos Component Writer's Guide"
HREF="cdl-guide.html"><LINK
REL="UP"
TITLE="The Build Process"
HREF="build.html"><LINK
REL="PREVIOUS"
TITLE="Configuration Header File Generation"
HREF="build.headers.html"><LINK
REL="NEXT"
TITLE="Building Test Cases"
HREF="build.tests.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>The <SPAN
CLASS="APPLICATION"
>eCos</SPAN
> Component Writer's Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="build.headers.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 4. The Build Process</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="build.tests.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="BUILD.MAKE">Building eCos</H1
><P
>The primary goal of an eCos build is to produce the library
<TT
CLASS="FILENAME"
>libtarget.a</TT
>. A typical <SPAN
CLASS="APPLICATION"
>eCos</SPAN
> build will also
generate a number of other targets: <TT
CLASS="FILENAME"
>extras.o</TT
>,
startup code <TT
CLASS="FILENAME"
>vectors.o</TT
>, and a linker script. Some
packages may cause additional libraries or targets to be generated.
The basic build process involves a number of different phases with
corresponding priorities. There are a number of predefined priorities:</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN2457"><P
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><THEAD
><TR
><TH
WIDTH="50%"
ALIGN="RIGHT"
VALIGN="TOP"
>Priority</TH
><TH
WIDTH="50%"
ALIGN="LEFT"
VALIGN="TOP"
>Action</TH
></TR
></THEAD
><TBODY
><TR
><TD
WIDTH="50%"
ALIGN="RIGHT"
VALIGN="TOP"
>0</TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="TOP"
>Export header files</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="RIGHT"
VALIGN="TOP"
>100</TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="TOP"
>Process <SPAN
CLASS="PROPERTY"
>compile</SPAN
> properties</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="RIGHT"
VALIGN="TOP"
> </TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="TOP"
>and most <SPAN
CLASS="PROPERTY"
>make_object</SPAN
> custom build steps</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="RIGHT"
VALIGN="TOP"
>200</TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="TOP"
>Generate libraries</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="RIGHT"
VALIGN="TOP"
>300</TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="TOP"
>Process <SPAN
CLASS="PROPERTY"
>make</SPAN
> custom build steps</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
><P
>Generation of the <TT
CLASS="FILENAME"
>extras.o</TT
> file, the startup code
and the linker script actually happens via <SPAN
CLASS="PROPERTY"
>make</SPAN
> custom build steps,
typically defined in appropriate HAL packages. The component framework
has no special knowledge of these targets.</P
><P
>By default custom build steps for a <SPAN
CLASS="PROPERTY"
>make_object</SPAN
> property happen
during the same phase as most compilations, but this can be changed
using a <TT
CLASS="LITERAL"
>-priority</TT
> option. Similarly custom build
steps for a <SPAN
CLASS="PROPERTY"
>make</SPAN
> property happen at the end of a build, but this can
also be changed with a <TT
CLASS="LITERAL"
>-priority</TT
> option. For
example a priority of 50 can be used to run a custom build step
between the header file export phase and the main compilation phase.
Custom build steps are discussed in more detail below.</P
><P
>Some build systems may run several commands of the same priority in
parallel. For example files listed in <SPAN
CLASS="PROPERTY"
>compile</SPAN
> properties may get
compiled in parallel, concurrently with <SPAN
CLASS="PROPERTY"
>make_object</SPAN
> custom build
steps with default priorities. Since most of the time for an <SPAN
CLASS="APPLICATION"
>eCos</SPAN
>
build involves processing <SPAN
CLASS="PROPERTY"
>compile</SPAN
> properties, this allows builds to
be speeded up on suitable host hardware. All build steps for a given
phase will complete before the next phase is started.</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="BUILD.MAKE.UPDATE">Updating the Build Tree</H2
><P
>Some build systems may involve a phase before the header files get
exported, to update the build and install trees automatically when
there has been a change to the configuration savefile
<TT
CLASS="FILENAME"
>ecos.ecc</TT
>. This is useful mainly for application
developers using the command line tools: it would allow users to
create the build tree only once, and after any subsequent
configuration changes the tree would be updated automatically by the
build system. The facility would be analogous to the
<TT
CLASS="LITERAL"
>--enable-maintainer-mode</TT
> option provide by the
<SPAN
CLASS="APPLICATION"
>autoconf</SPAN
> and <SPAN
CLASS="APPLICATION"
>automake</SPAN
> programs. At present no <SPAN
CLASS="APPLICATION"
>eCos</SPAN
>
build system implements this functionality, but it is likely to be
added in a future release.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="BUILD.MAKE.EXPORT">Exporting Public Header Files</H2
><P
>The first compulsory phase involves making sure that there is an up to
date set of header files in the install tree. Each package can contain
some number of header files defining the exported interface.
Applications should only use exported functionality. A package can
also contain some number of private header files which are only of
interest to the implementation, and which should not be visible to
application code. The various packages that go into a particular
configuration can be spread all over the component repository. In
theory it might be possible to make all the exported header files
accessible by having a lengthy <TT
CLASS="LITERAL"
>-I</TT
> header file
search path, but this would be inconvenient both for building eCos and
for building applications. Instead all the relevant header files are
copied to a single location, the <TT
CLASS="FILENAME"
>include</TT
> subdirectory of the install tree.
The process involves the following:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>The install tree, for example <TT
CLASS="FILENAME"
>/usr/local/ecos/install</TT
>, and its <TT
CLASS="FILENAME"
>include</TT
> subdirectory <TT
CLASS="FILENAME"
>/usr/local/ecos/install/include</TT
> will typically be
created when the build tree is generated or updated. At the same time
configuration header files will be written to the <TT
CLASS="FILENAME"
>pkgconf</TT
> subdirectory, for example
<TT
CLASS="FILENAME"
>/usr/local/ecos/include/pkgconf</TT
>, so that
the configuration data is visible to all the packages and to
application code that may wish to examine some of the configuration
options.</P
></LI
><LI
><P
>Each package in the configuration is examined for exported header
files. The exact order in which the packages are processed is not
defined, but should not matter.</P
><P
></P
><OL
TYPE="a"
><LI
><P
>If the package has an <A
HREF="ref.include-files.html"
><SPAN
CLASS="PROPERTY"
>include_files</SPAN
></A
> property then this
lists all the exported header files:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_package <some_package> {
…
include_files header1.h header2.h
} </PRE
></TD
></TR
></TABLE
><P
>If no arguments are given then the package does not export any header
files.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_package <some_package> {
…
include_files
} </PRE
></TD
></TR
></TABLE
><P
>The listed files may be in an <TT
CLASS="FILENAME"
>include</TT
> subdirectory within the package's
hierarchy, or they may be relative to the package's toplevel
directory. The <SPAN
CLASS="PROPERTY"
>include_files</SPAN
> property is intended mainly for very
simple packages. It can also be useful when converting existing code
to an <SPAN
CLASS="APPLICATION"
>eCos</SPAN
> package, to avoid rearranging the sources.</P
></LI
><LI
><P
>If there is no <SPAN
CLASS="PROPERTY"
>include_files</SPAN
> property then the component framework
will look for an <TT
CLASS="FILENAME"
>include</TT
>
subdirectory in the package, as per the layout conventions. All files,
including those in subdirectories, will be treated as exported header
files. For example, the math library package contains files <TT
CLASS="FILENAME"
>include/math.h</TT
> and <TT
CLASS="FILENAME"
>include/sys/ieeefp.h</TT
>, both of which will
be exported to the install tree.</P
></LI
><LI
><P
>As a last resort, if there is neither an <SPAN
CLASS="PROPERTY"
>include_files</SPAN
> property nor
an <TT
CLASS="FILENAME"
>include</TT
> subdirectory, the
component framework will search the package's toplevel directory and
all of its subdirectories for files with one of the following
suffixes: <TT
CLASS="LITERAL"
>.h</TT
>, <TT
CLASS="LITERAL"
>.hxx</TT
>,
<TT
CLASS="LITERAL"
>.inl</TT
> or <TT
CLASS="LITERAL"
>.inc</TT
>. All such files
will be interpreted as exported header files.</P
><P
>This last resort rule could cause confusion for packages which have no
exported header files but which do contain one or more private header
files. For example a typical device driver simply implements an
existing interface rather than define a new one, so it does not need
to export a header file. However it may still have one or more private
header files. Such packages should use an <SPAN
CLASS="PROPERTY"
>include_files</SPAN
> property
with no arguments.</P
></LI
></OL
></LI
><LI
><P
>If the package has one or more exported header files, the next step is
to determine where the files should end up. By default all exported
header files will just end up relative to the install tree's <TT
CLASS="FILENAME"
>include</TT
> subdirectory. For example the
math library's <TT
CLASS="FILENAME"
>math.h</TT
> header
would end up as <TT
CLASS="FILENAME"
>/usr/local/ecos/include/math.h</TT
>,
and the <TT
CLASS="FILENAME"
>sys/ieeefp.h</TT
> header
would end up as
<TT
CLASS="FILENAME"
>/usr/local/ecos/include/sys/ieeefp.h</TT
>. This
behaviour is correct for packages like the C library where the
interface is defined by appropriate standards. For other packages this
behaviour can lead to file name clashes, and the <A
HREF="ref.include-dir.html"
><SPAN
CLASS="PROPERTY"
>include_dir</SPAN
></A
> property should be used
to avoid this:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_package CYGPKG_KERNEL {
include_dir cyg/kernel
}</PRE
></TD
></TR
></TABLE
><P
>This means that the kernel's exported header file
<TT
CLASS="FILENAME"
>include/kapi.h</TT
> should be copied to
<TT
CLASS="FILENAME"
>/usr/local/ecos/include/cyg/kernel/kapi.h</TT
>, where
it is very unlikely to clash with a header file from some other
package.</P
></LI
><LI
><P
>For typical application developers there will be little or no need for
the installed header files to change after the first build. Changes
will be necessary only if packages are added to or removed from the
configuration. For component writers, the build system should detect
changes to the master copy of the header file source code and update
the installed copies automatically during the next build. The build
system is expected to perform a header file dependency analysis, so
any source files affected should get rebuilt as well.</P
></LI
><LI
><P
>Some build systems may provide additional support for application
developers who want to make minor changes to a package, especially for
debugging purposes. A header file could be copied from the
component repository (which for application developers is assumed to
be a read-only resource) into the build tree and edited there. The
build system would detect a more recent version of such a header file
in the build tree and install it. Care would have to be taken to
recover properly if the modified copy in the build tree is
subsequently removed, in order to revert to the original behaviour.</P
></LI
><LI
><P
>When updating the install tree's <TT
CLASS="FILENAME"
>include</TT
> subdirectory, the build tree may
also perform a clean-up operation. Specifically, it may check for any
files which do not correspond to known exported header files and
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
…
}</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 <some_option> {
…
compile file1.c file2.c file3.c
}
cdl_option <some_option> {
…
compile file1.c
compile file2.c
compile file3.c
}
cdl_option <some_option> {
…
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"
><object file> : <source file>
$(CC) -c $(INCLUDE_PATH) $(CFLAGS) -o $@ $<</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 <SOME_PACKAGE> {
…
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 {
…
}</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%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_component CYGBLD_GLOBAL_OPTIONS {
flavor none
parent CYGPKG_NONE
…
cdl_option CYGBLD_GLOBAL_COMMAND_PREFIX {
flavor data
default_value { "arm-elf" }
…
}
cdl_option CYGBLD_GLOBAL_CFLAGS {
flavor data
default_value "-Wall -g -O2 …"
…
}
cdl_option CYGBLD_GLOBAL_LDFLAGS {
flavor data
default_value "-g -nostdlib -Wl,--gc-sections …"
…
}
}</PRE
></TD
></TR
></TABLE
><P
>The <TT
CLASS="VARNAME"
>CYGBLD_GLOBAL_OPTIONS</TT
> component serves to
collect together all global build-related options. It has the flavor
<TT
CLASS="LITERAL"
>none</TT
> since disabling all of these options would
make it impossible to build anything and hence is not useful. It is
parented immediately below the root of the configuration hierarchy,
thus making sure that it is readily accessible in the graphical
configuration tool and, for command line users, in the
<TT
CLASS="FILENAME"
>ecos.ecc</TT
> save file.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>Currently the <SPAN
CLASS="PROPERTY"
>parent</SPAN
> property lists a parent of
<TT
CLASS="VARNAME"
>CYGPKG_NONE</TT
>, rather than an empty string. This
could be unfortunate if there was ever a package with that name. The
issue will be addressed in a future release of the component
framework.</P
></BLOCKQUOTE
></DIV
><P
>The option <TT
CLASS="VARNAME"
>CYGBLD_GLOBAL_COMMAND_PREFIX</TT
> defines
which tools should be used for the current target. Typically this is
determined by the processor on the target hardware. In some cases a
given target board may be able to support several different
processors, in which case the <SPAN
CLASS="PROPERTY"
>default_value</SPAN
> expression could select
a different toolchain depending on some other option that is used to
control which particular processor.
<TT
CLASS="VARNAME"
>CYGBLD_GLOBAL_COMMAND_PREFIX</TT
> is modifiable rather
than calculated, so users can override this when necessary.</P
><P
>Given a command prefix such as <TT
CLASS="LITERAL"
>arm-elf</TT
>, all C
source files will be compiled with <TT
CLASS="LITERAL"
>arm-elf-gcc</TT
>, all
C++ sources will be built using <TT
CLASS="LITERAL"
>arm-elf-g++</TT
>,
and <TT
CLASS="LITERAL"
>arm-elf-ar</TT
> will be used to generate the
library. This is in accordance with the usual naming conventions for
GNU cross-compilers and similar tools. For the purposes of custom
build steps, tokens such as <TT
CLASS="LITERAL"
>$(CC)</TT
> will be set to
<TT
CLASS="LITERAL"
>arm-elf-gcc</TT
>.</P
><P
>The next option, <TT
CLASS="VARNAME"
>CYGBLD_GLOBAL_CFLAGS</TT
>, is used to
provide the initial value of <TT
CLASS="LITERAL"
>$(CFLAGS)</TT
>. Some
compiler flags such as <TT
CLASS="LITERAL"
>-Wall</TT
> and
<TT
CLASS="LITERAL"
>-g</TT
> are likely to be used on all targets. Other
flags such as <TT
CLASS="LITERAL"
>-mcpu=arm7tdmi</TT
> will be
target-specific. Again this is a modifiable option, so the user can
switch from say <TT
CLASS="LITERAL"
>-O2</TT
> to <TT
CLASS="LITERAL"
>-Os</TT
> if
desired. The option <TT
CLASS="VARNAME"
>CYGBLD_GLOBAL_LDFLAGS</TT
> serves
the same purpose for <TT
CLASS="LITERAL"
>$(LDFLAGS)</TT
> and linking. It is
used primarily when building test cases or possibly for some custom
build steps, since building eCos itself generally involves building
one or more libraries rather than executables.</P
><P
>Some packages may wish to add certain flags to the global set, or
possibly remove some flags. This can be achieved by having
appropriately named options in the package, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_component CYGPKG_KERNEL_OPTIONS {
display "Kernel build options"
flavor none
…
cdl_option CYGPKG_KERNEL_CFLAGS_ADD {
display "Additional compiler flags"
flavor data
default_value { "" }
…
}
cdl_option CYGPKG_KERNEL_CFLAGS_REMOVE {
display "Suppressed compiler flags"
flavor data
default_value { "" }
…
}
cdl_option CYGPKG_KERNEL_LDFLAGS_ADD {
display "Additional linker flags"
flavor data
default_value { "" }
…
}
cdl_option CYGPKG_KERNEL_LDFLAGS_REMOVE {
display "Suppressed linker flags"
flavor data
default_value { "" }
…
}
}</PRE
></TD
></TR
></TABLE
><P
>In this example the kernel does not modify the global compiler flags
by default, but it is possible for the users to modify the options if
desired. The value of <TT
CLASS="LITERAL"
>$(CFLAGS)</TT
> that is used for
the compilations and custom build steps in a given package is
determined as follows:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>Start with the global settings from
<TT
CLASS="VARNAME"
>CYGBLD_GLOBAL_CFLAGS</TT
>, for example
<TT
CLASS="LITERAL"
>-g -O2</TT
>.</P
></LI
><LI
><P
>Remove any flags specified in the per-package
<TT
CLASS="LITERAL"
>CFLAGS_REMOVE</TT
> option, if any. For example
if <TT
CLASS="LITERAL"
>-O2</TT
> should be removed for this package then
<TT
CLASS="LITERAL"
>$(CFLAGS)</TT
> would now have a value of just
<TT
CLASS="LITERAL"
>-g</TT
>.</P
></LI
><LI
><P
>Then concatenate the flags specified by the per-package
<TT
CLASS="LITERAL"
>CFLAGS_ADD</TT
> option, if any. For example if
<TT
CLASS="LITERAL"
>-Os</TT
> should be added for the current package then
the final value of <TT
CLASS="LITERAL"
>$(CFLAGS)</TT
> will be
<TT
CLASS="LITERAL"
>-g -Os</TT
>.</P
></LI
></OL
><P
><TT
CLASS="LITERAL"
>$(LDFLAGS)</TT
> is determined in much the same way.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>The way compiler flags are handled at present has numerous limitations
that need to be addressed in a future release, although it should
suffice for nearly all cases. For the time being custom build steps
and in particular the <SPAN
CLASS="PROPERTY"
>make_object</SPAN
> property can be used to work
around the limitations.</P
><P
>Amongst the issues, there is a specific problem with package
encapsulation. For example the math library imposes some stringent
requirements on the compiler in order to guarantee exact IEEE
behavior, and may need special flags on a per-architecture basis. One
way of handling this is to have
<TT
CLASS="VARNAME"
>CYGPKG_LIBM_CFLAGS_ADD</TT
> and
<TT
CLASS="VARNAME"
>CYGPKG_LIBM_CFLAGS_REMOVE</TT
> <SPAN
CLASS="PROPERTY"
>default_value</SPAN
>
expressions which depend on the target architecture, but such
expressions may have to updated for each new architecture. An
alternative approach would allow the architectural HAL package to
modify the <SPAN
CLASS="PROPERTY"
>default_value</SPAN
> expressions for the math library, but this
breaks encapsulation. A third approach would allow some architectural
HAL packages to define one or more special options with well-known
names, and the math library could check if these options were defined
and adjust the default values appropriately. Other packages with
floating point requirements could do the same. This approach also has
scalability issues, in particular how many such categories of options
would be needed? It is not yet clear how best to resolve such issues.</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>When generating a build tree it would be desirable for the component
framework to output details of the tools and compiler flags in a
format that can be re-used for application builds, for example a
makefile fragment. This would make it easier for application
developers to use the same set of flags as were used for building eCos
itself, thus avoiding some potential problems with incompatible
compiler flags.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="BUILD.CUSTOM">Custom Build Steps</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 custom build steps as 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
>For most packages simply listing one or more source files in a
<SPAN
CLASS="PROPERTY"
>compile</SPAN
> property is sufficient. These files will get built using the
appropriate compiler and compiler flags and added to a library, which
then gets linked with application code. A package that can be built in
this way is likely to be more portable to different targets and build
environments, since it avoids build-time dependencies. However some
packages have special needs, and the component framework supports
custom build steps to allow for these needs. There are two properties
related to this, <SPAN
CLASS="PROPERTY"
>make</SPAN
> and <SPAN
CLASS="PROPERTY"
>make_object</SPAN
>, and both take the following
form:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> make {
<target_filepath> : <dependency_filepath> …
<command>
...
}</PRE
></TD
></TR
></TABLE
><P
>Although this may look like makefile syntax, and although some build
environments will indeed involve generating makefiles and running
<SPAN
CLASS="APPLICATION"
>make</SPAN
>, this is not
guaranteed. It is possible for the component framework to be
integrated with some other build system, and custom build steps should
be written with that possibility in mind. Each custom build step
involves a target, some number of dependency files, and some number of
commands. If the target is not up to date with respect to one or more
of the dependencies then the commands need to be executed.</P
><P
></P
><OL
TYPE="a"
><LI
><P
>Only one target can be specified. For a <SPAN
CLASS="PROPERTY"
>make_object</SPAN
> property this
target must be an object file. For a <SPAN
CLASS="PROPERTY"
>make</SPAN
> property it can be any
file. In both cases it must refer to a physical file, the use of
phony targets is not supported. The target should not be an absolute
path name. If the generated file needs to end up in the install tree
then this can be achieved using a <TT
CLASS="LITERAL"
><PREFIX></TT
>
token, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> make {
<PREFIX>/lib/mytarget : …
...
}</PRE
></TD
></TR
></TABLE
><P
>When the build tree is generated and the custom build step is added to
the makefile (or whatever build system is used)
<TT
CLASS="LITERAL"
><PREFIX></TT
> will be replaced with the absolute
path to the install tree. </P
></LI
><LI
><P
>All the dependencies must also refer to physical files, not to phony
targets. These files may be in the source tree. The
<TT
CLASS="LITERAL"
><PACKAGE></TT
> token can be used to indicate this:
when the build tree is generated this token will be replaced with the
absolute path to the package's root directory in the component
repository, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> make_object {
xyzzy.o : <PACKAGE>/src/xyzzy.c
…</PRE
></TD
></TR
></TABLE
><P
>If the component repository was installed in <TT
CLASS="FILENAME"
>/usr/local/ecos</TT
> and this custom build
step existed in version 1_5 of the kernel,
<TT
CLASS="LITERAL"
><PACKAGE></TT
> would be replaced with
<TT
CLASS="FILENAME"
>/usr/local/ecos/packages/kernel/v1_5</TT
>.</P
><P
>Alternatively the dependencies may refer to files that are generated
during the build. These may be object files resulting from <SPAN
CLASS="PROPERTY"
>compile</SPAN
>
properties or other <SPAN
CLASS="PROPERTY"
>make_object</SPAN
> properties, or they may be other
files resulting from a <SPAN
CLASS="PROPERTY"
>make</SPAN
> property, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> compile plugh.c
make_object {
xyzzy.o : plugh.o
…
}</PRE
></TD
></TR
></TABLE
></LI
><LI
><P
>No other token or makefile variables may be used in the target or
dependency file names. Also conditionals such as
<TT
CLASS="LITERAL"
>ifneq</TT
> and similar makefile functionality must not
be used.</P
></LI
><LI
><P
>
Similarly the list of commands must not use any makefile conditionals
or similar functionality. A number of tokens can be used to provide
access to target-specific or environmental data. Note that these
tokens look like makefile variables, unlike the
<TT
CLASS="LITERAL"
><PREFIX></TT
> and
<TT
CLASS="LITERAL"
><PACKAGE></TT
> tokens mentioned earlier:</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN2778"><P
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><THEAD
><TR
><TH
ALIGN="LEFT"
VALIGN="TOP"
>Token</TH
><TH
ALIGN="LEFT"
VALIGN="TOP"
>Purpose</TH
><TH
ALIGN="LEFT"
VALIGN="TOP"
>Example value</TH
></TR
></THEAD
><TBODY
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>$(AR)</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>the GNU archiver</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>mips-tx39-elf-ar</TT
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>$(CC)</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>the GNU compiler</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>sh-elf-gcc</TT
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>$(CFLAGS)</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>compiler flags</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>-O2 -Wall</TT
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>$(COMMAND_PREFIX)</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>the triplet prefix</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>mn10300-elf-</TT
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>$(INCLUDE_PATH></TT
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>header file search path</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>-I. -Isrc/misc</TT
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>$(LDFLAGS)</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>linker flags</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>-nostdlib -Wl,-static</TT
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>$(OBJCOPY)</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>the objcopy utility</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>arm-elf-objcopy</TT
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>$(PREFIX)</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>location of the install tree</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="FILENAME"
>/home/fred/ecos-install</TT
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>$(REPOSITORY)</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>location of the component repository</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="FILENAME"
>/home/fred/ecos/packages</TT
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
><P
>In addition commands in a custom build step may refer to the target
and the dependencies using <TT
CLASS="LITERAL"
>$@</TT
>,
<TT
CLASS="LITERAL"
>$<</TT
>, <TT
CLASS="LITERAL"
>$^</TT
> and
<TT
CLASS="LITERAL"
>$*</TT
>, all of which behave as per GNU make syntax. The
commands will execute in a suitable directory in the build tree.</P
></LI
><LI
><P
>The current directory used during a custom build step 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, and that this will be the current
directory. In addition any object files generated as a result of
<SPAN
CLASS="PROPERTY"
>compile</SPAN
> properties will be located here as well, which is useful for
custom build steps that depend on a <TT
CLASS="LITERAL"
>.o</TT
> file
previously generated.</P
><P
>Any temporary files created by a custom build step should be generated
in the build tree (in or under the current directory). Such files
should be given a <TT
CLASS="FILENAME"
>.tmp</TT
> file extension to ensure
that they are deleted during a <TT
CLASS="LITERAL"
>make clean</TT
> or
equivalent operation.</P
><P
>If a package contains multiple custom build steps with the same
priority, it is possible that these build steps will be run
concurrently. Therefore these custom build steps must not accidentally
use the same file names for intermediate files.</P
></LI
><LI
><P
>Care has to be taken to make sure that the commands in a custom build
step will run on all host platforms, including Windows NT as well as
Linux and other Unix systems. For example, all file paths should use
forward slashes as the directory separator. It can be assumed that
Windows users will have a full set of CygWin tools installed and
available on the path. The <A
HREF="http://www.gnu.org/prep/standards.html"
TARGET="_top"
>GNU coding
standards</A
> provide some useful guidelines for writing portable
build rules.</P
></LI
><LI
><P
>A custom build step must not make any assumptions concerning the
version of another package. This enforces package encapsulation,
preventing one package from accessing the internals of another.</P
></LI
><LI
><P
>No assumptions should be made about the target platform, unless the
package is inherently specific to that platform. Even then it is
better to use the various tokens whenever possible, rather than
hard-coding in details such as the compiler. For example, given a
custom build step such as:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> arm-elf-gcc -c -mcpu=arm7di -o $@ $<</PRE
></TD
></TR
></TABLE
><P
>Even if this build step will only be invoked on ARM targets, it could
cause problems. For example the toolchain may have been installed
using a prefix other than <TT
CLASS="LITERAL"
>arm-elf</TT
>. Also, if the
user changes the compiler flags then this would not be reflected in
the build step. The correct way to write this rule would be:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> $(CC) -c $(CFLAGS) -o $@ $<</PRE
></TD
></TR
></TABLE
><P
>Some commands such as the compiler, the archiver, and objcopy are
required sufficiently often to warrant their own tokens, for example
<TT
CLASS="LITERAL"
>$(CC)</TT
> and <TT
CLASS="LITERAL"
>$(OBJCOPY)</TT
>. Other
target-specific commands are needed only rarely and the
<TT
CLASS="LITERAL"
>$(COMMAND_PREFIX)</TT
> token can be used to construct
the appropriate command name, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> $(COMMAND_PREFIX)size $< > $@</PRE
></TD
></TR
></TABLE
></LI
><LI
><P
>Custom build steps should not be used to build host-side executables,
even if those executables are needed to build parts of the target side
code. Support for building host-side executables will be added in a
future version of the component framework, although it will not
necessarily involve these custom build steps.</P
></LI
></OL
><P
>By default custom build steps defined in a <SPAN
CLASS="PROPERTY"
>make_object</SPAN
> property
have a priority of 100, which means that they will be executed
in the same phase as compilations resulting from a <SPAN
CLASS="PROPERTY"
>compile</SPAN
> property.
It is possible to change the priority using a property option, for
example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> make_object -priority 50 {
…
}</PRE
></TD
></TR
></TABLE
><P
>Specifying a priority smaller than a 100 means that the custom build
step happens before the normal compilations. Priorities between 100
and 200 happen after normal compilations but before the libraries are
archived together. <SPAN
CLASS="PROPERTY"
>make_object</SPAN
> properties should not specify a
priority of 200 or later. </P
><P
>Custom build steps defined in a <SPAN
CLASS="PROPERTY"
>make</SPAN
> property have a default
priority of 300, and so they will happen after the libraries have been
built. Again this can be changed using a <TT
CLASS="LITERAL"
>-priority</TT
>
property option.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="BUILD.STARTUP">Startup Code</H2
><P
>Linking an application requires the application code, a linker script,
the eCos library or libraries, the <TT
CLASS="LITERAL"
>extras.o</TT
> file,
and some startup code. Depending on the target hardware and how the
application gets booted, this startup code may do little more than
branching to <TT
CLASS="LITERAL"
>main()</TT
>, or it may have to perform a
considerable amount of hardware initialization. The startup code
generally lives in a file <TT
CLASS="LITERAL"
>vectors.o</TT
> which is
created by a custom build step in a HAL package. As far as application
developers are concered the existence of this file is largely
transparent, since the linker script ensures that the file is part of
the final executable.</P
><P
>This startup code is not generally of interest to component writers,
only to HAL developers who are referred to one of the existing HAL
packages for specific details. Other packages are not expected to
modify the startup in any way. If a package needs some work performed
early on during system initialization, before the application's main
entry point gets invoked, this can be achieved using a static object
with a suitable constructor priority.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>It is possible that the <TT
CLASS="LITERAL"
>extras.o</TT
> support, in
conjunction with appropriate linker script directives, could be used
to eliminate the need for a special startup file. The details are not
yet clear.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="BUILD.LINKERSCRIPT">The Linker Script</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
>This section is not finished, and the details are subject to change in
a future release. Arguably linker script issues should be documented
in the HAL documentation rather than in this guide.</P
></TD
></TR
></TABLE
></DIV
><P
>Generating the linker script is the responsibility of the various HAL
packages that are applicable to a given target. Developers of
components other than HAL packages need not be concerned about what is
involved. Developers of new HAL packages should use an existing HAL as
a template.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>It may be desirable for some packages to have some control over the
linker script, for example to add extra alignment details for a
particular section. This can be risky because it can result in subtle
portability problems, and the current component framework has no
support for any such operations. The issue may be addressed in a
future release.</P
></BLOCKQUOTE
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="build.headers.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="cdl-guide.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="build.tests.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Configuration Header File Generation</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="build.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Building Test Cases</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>