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&#62;</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"
>$&#60;</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&nbsp;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 $@ $&lt;</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 $@ $&lt;</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"
>&#13;    $(COMMAND_PREFIX)size $&lt; &gt; $@</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 {
        &#8230;
    }</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
>