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