build.sgml

ecos实时嵌入式操作系统

to an &eCos; package, to avoid rearranging the sources.
</para>
</listitem>
<listitem>
<para>
If there is no &include-files; property then the component framework
will look for an <filename class="directory">include</filename>
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 <filename
class="headerfile">include/math.h</filename> and <filename
class="headerfile">include/sys/ieeefp.h</filename>, both of which will
be exported to the install tree.
</para>
</listitem>
<listitem>
<para>
As a last resort, if there is neither an &include-files; property nor
an <filename class="directory">include</filename> subdirectory, the
component framework will search the package's toplevel directory and
all of its subdirectories for files with one of the following
suffixes: <literal>.h</literal>, <literal>.hxx</literal>,
<literal>.inl</literal> or <literal>.inc</literal>. All such files
will be interpreted as exported header files.
</para>
<para>
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 &include-files; property
with no arguments.
</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>
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 <filename
class="directory">include</filename> subdirectory. For example the
math library's <filename class="headerfile">math.h</filename> header
would end up as <filename>/usr/local/ecos/include/math.h</filename>,
and the <filename class="headerfile">sys/ieeefp.h</filename> header
would end up as
<filename>/usr/local/ecos/include/sys/ieeefp.h</filename>. 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 <link
linkend="ref.include-dir">&include-dir;</link> property should be used
to avoid this:
</para>
<programlisting width=72>
cdl_package CYGPKG_KERNEL {
    include_dir cyg/kernel
}
</programlisting>
<para>
This means that the kernel's exported header file
<filename>include/kapi.h</filename> should be copied to
<filename>/usr/local/ecos/include/cyg/kernel/kapi.h</filename>, where
it is very unlikely to clash with a header file from some other
package.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
When updating the install tree's <filename
class="directory">include</filename> 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.
</para>
</listitem>
</orderedlist>
<note>
<para>
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.
</para>
</note>
</sect2>

<!-- }}} -->
<!-- {{{ Compiling              -->

<sect2 id="build.make.compiles">
<title>Compiling</title>

<para>
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 &compile; properties in the &CDL;
scripts for the various packages, for example:
</para>
<programlisting width=72>
cdl_package CYGPKG_ERROR {
    display       "Common error code support"
    compile       strerror.cxx
    &hellip;
}
</programlisting>
<para>
&compile; properties may appear in the body of a &cdl-package;,
&cdl-component;, &cdl-option; or &cdl-interface;. If the option or
other &CDL; 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 &compile; property to list multiple source files, and
it is also possible for a given &CDL; entity to contain multiple
&compile; properties. The following three examples are equivalent:
</para>
<programlisting width=72>
cdl_option &lt;some_option&gt; {
    &hellip;
    compile file1.c file2.c file3.c
}

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

cdl_option &lt;some_option&gt; {
    &hellip;
    compile file1.c file2.c
    compile file3.c
}
</programlisting>
<para>
Packages that follow the directory layout conventions should have a
subdirectory <filename class="directory">src</filename>, 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 <filename>strerror.cxx</filename> then the following two lines
are equivalent:
</para>
<programlisting width=72>
    compile strerror.cxx
    compile src/strerror.cxx
</programlisting>
<para>
In the first case the component framework will find the file
immediately in the packages <filename class="directory">src</filename>
subdirectory. In the second case the framework will first look for a
file <filename>src/src/strerror.cxx</filename>, and then for
<filename>str/strerror.cxx</filename> relative to the package's root
directory. The result is the same.
</para>
<para>
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 <filename>src/sync/mutex.cxx</filename> then the corresponding
&CDL; entry would be:
</para>
<programlisting width=72>
    compile sync/mutex.cxx
</programlisting>
<para>
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:
</para>
<programlisting width=72>
&lt;object file&gt; : &lt;source file&gt;
        $(CC) -c $(INCLUDE_PATH) $(CFLAGS) -o $@ $<
</programlisting>

<para>
The component framework has built-in knowledge for processing source
files written in C, C++ or assembler. These should have a
<literal>.c</literal>, <literal>.cxx</literal> and
<literal>.S</literal> 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.
</para>
<para>
The compiler command that will be used is something like
<literal>arm-elf-gcc</literal>. This consists of a command prefix, in
this case <literal>arm-elf</literal>, and a specific command such as
<literal>gcc</literal>. 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.
</para>
<para>
The <literal>$(INCLUDE_PATH)</literal> header file search path
consists of at least the following:
</para>
<orderedlist>
<listitem>
<para>
The <filename class="directory">include</filename> 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.
</para>
</listitem>
<listitem>
<para>
The current package's root directory. This ensures that all files in
the package are accessible at build time.
</para>
</listitem>
<listitem>
<para>
The current package's <filename class="directory">src</filename>
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.
</para>
</listitem>
</orderedlist>
<para>
The compiler flags <literal>$(CFLAGS)</literal> 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
<literal>-mcpu=arm9</literal>, various flags related to warnings,
debugging and optimization, and flags such as
<literal>-finit-priority</literal> which are needed by &eCos; 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.
</para>
<para>
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.
</para>
<para>
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.
</para>

</sect2>

<!-- }}} -->
<!-- {{{ Library Generation     -->

<sect2 id="build.make.libraries">
<title>Generating the Libraries</title>

<para>
Once all the &compile; and &make-object; 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 <application class="software">ar</application> command
corresponding to the current architecture, for example <application
class="software">powerpc-eabi-ar</application>. By default al of the
object files will end up in a single library
<filename>libtarget.a</filename>. This can be changed on a per-package
basis using the <link linkend="ref.library">&library</link> property
in the body of the corresponding &cdl-package; command, for example:
</para>
<programlisting width=72>
cdl_package &lt;SOME_PACKAGE&gt; {
    &hellip;
    library  libSomePackage.a
}
</programlisting>

<para>
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
<filename>libtarget.a</filename> avoids any complications.
</para>
<para>
It is also possible to change the target library for individual files,
using a <literal>-library</literal> option with the corresponding
&compile; or &make-object; property. For example:
</para>
<programlisting width=72>
    compile -library=libSomePackage.a hello.c