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