build.sgml

ecos实时嵌入式操作系统

<para>
At present there is no way for application or package source code to
get hold of all the configuration details related to the current
hardware. Instead that information is spread over various different
configuration headers for the HAL and device driver packages, with
some of the information going into <filename
class="headerfile">pkgconf/system.h</filename>. It is possible that in
some future release of the system there will be another global
configuration header file <filename
class="headerfile">pkgconf/hardware.h</filename> which either contains the
configuration details for the various hardware-specific packages or
which <literal>#include's</literal> all the hardware-specific
configuration headers. The desirability and feasibility of such a
scheme are still to be determined. To avoid future incompatibility
problems as a result of any such changes, it is recommended that all
hardware packages (in other packages containing the &hardware;
property) use the &define-header; property to specify explicitly which
configuration header should be generated.
</para>
</note>

<sect2 id = "build.headers.system.h">
<title>The <filename class="headerfile">system.h</filename> Header</title>

<para>
Typically configuration header files are <literal>#include'd</literal>
only by the package's source code at build time, or by a package's
exported header files if the interface provided by the package may be
affected by a configuration option. There should be no need for
application code to know the details of individual configuration
options, instead the configuration should specifically meet the needs
of the application.
</para>
<para>
There are always exceptions. Application code may want to adapt to
configuration options, for example to do different things for ROM and
RAM booting systems, or when it is necessary to support several
different target boards. This is especially true if the code in question
is really re-usable library code which has not been converted to an
eCos package, and hence cannot use any CDL facilities.
</para>
<para>
A major problem here is determining which packages are in the
configuration: attempting to <literal>#include</literal> a header file
such as <filename class="headerfile">pkgconf/net.h</filename>
when it is not known for certain that that particular package is part
of the configuration will result in compilation errors. The global
header file <filename class="headerfile">pkgconf/system.h</filename>
serves to provide such information, so application code can use
techniques like the following:
</para>

<programlisting width=72>
#include &lt;pkgconf/system.h&gt;
#ifdef CYGPKG_NET
# include &lt;pkgconf/net.h&gt;
#endif
</programlisting>

<para>
This will compile correctly irrespective of the eCos configuration,
and subsequent code can use <literal>#ifdef</literal> or similar
directives on <literal>CYGPKG_NET</literal> or any of the
configuration options in that package. 
</para>
<para>
In addition to determining whether or not a package is present, the
global configuration header file can also be used to find out the
specific version of a package that is being used. This can be useful
if a more recent version exports additional functionality. It may also
be necessary to adapt to incompatible changes in the exported
interface or to changes in behaviour. For each package the
configuration system will typically <literal>#define</literal> three
symbols, for example for a V1.3.1 release:
</para>
<programlisting width=72>
#define CYGNUM_NET_VERSION_MAJOR 1
#define CYGNUM_NET_VERSION_MINOR 3
#define CYGNUM_NET_VERSION_RELEASE 1
</programlisting>
<para>
There are a number of problems associated with such version
<literal>#define's</literal>. The first restriction is that the
package must follow the standard naming conventions, so the package
name must be of the form <literal>xxxPKG_yyy</literal>. The three
characters immediately preceding the first underscore must be
<literal>PKG</literal>, and will be replaced with
<literal>NUM</literal> when generating the version
<literal>#define's</literal>. If a package does not follow the naming
convention then no version <literal>#define's</literal> will be
generated. 
</para>
<para>
Assuming the package does follow the naming conventions, the
configuration tools will always generate three version
<literal>#define's</literal> for the major, minor, and release
numbers. The symbol names are obtained from the package name by
replacing <literal>PKG</literal> with <literal>NUM</literal> and
appending <literal>_VERSION_MAJOR</literal>,
<literal>_VERSION_MINOR</literal> and
<literal>_VERSION_RELEASE</literal>. It is assumed that the resulting
symbols will not clash with any configuration option names. The values
for the <literal>#define's</literal> are determined by searching the
version string for sequences of digits, optionally preceded by a minus
sign. It is possible that some or all of the numbers are absent in any
given version string, in which case <literal>-1</literal> will be used
in the <literal>#define</literal>. For example, given a version string
of <literal>V1.12beta</literal>, the major version number is
<literal>1</literal>, the minor number is <literal>12</literal>, and
the release number is <literal>-1</literal>. Given a version string of
<literal>beta</literal> all three numbers would be set to
<literal>-1</literal>.
</para>
<para>
There is special case code for the version <literal>current</literal>,
which typically corresponds to a development version obtained via
anonymous CVS or similar means. The configuration system has special
built-in knowledge of this version, and will assume it is more recent
than any specific release number. The global configuration header
defines a special symbol <literal>CYGNUM_VERSION_CURRENT</literal>,
and this will be used as the major version number when version
<literal>current</literal> of a package is used:
</para>
<programlisting width=72>
#define CYGNUM_VERSION_CURRENT 0x7fffff00
...
#define CYGNUM_INFRA_VERSION_MAJOR CYGNUM_VERSION_CURRENT
#define CYGNUM_INFRA_VERSION_MINOR -1
#define CYGNUM_INFRA_VERSION_RELEASE -1
</programlisting>

<para>
The large number used for <literal>CYGNUM_VERSION_CURRENT</literal>
should ensure that major version comparisons work as expected, while
still allowing for a small amount of arithmetic in case that proves
useful. 
</para>
<para>
It should be noted that this implementation of version
<literal>#define's</literal> will not cope with all version number
schemes. However for many cases it should suffice.
</para>

</sect2>

</sect1>

<!-- }}} -->
<!-- {{{ The Build              -->

<sect1 id="build.make">
<title>Building eCos</title>

<!-- {{{ Introit                -->

<para>
The primary goal of an eCos build is to produce the library
<filename>libtarget.a</filename>. A typical &eCos; build will also
generate a number of other targets: <filename>extras.o</filename>,
startup code <filename>vectors.o</filename>, 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:
</para>
<informaltable frame="all" colsep=1 rowsep=1 pgwide=0>
<tgroup cols=2 colsep=1 rowsep=1>
<colspec colnum=1 align=right>
<colspec colnum=2 align=left>
<thead>
  <row>
    <entry>Priority</entry>
    <entry>Action</entry>
  </row>
</thead>
<tbody>
  <row>
    <entry>0</entry>
    <entry>Export header files</entry>
  </row>
  <row>
    <entry>100</entry>
    <entry>Process &compile; properties</entry>
  </row>
  <row>
    <entry> </entry>
    <entry>and most &make-object; custom build steps</entry>
  </row>
  <row>
    <entry>200</entry>
    <entry>Generate libraries</entry>
  </row>
  <row>
    <entry>300</entry>
    <entry>Process &make; custom build steps</entry>
  </row>
</tbody>
</tgroup>
</informaltable>

<para>
Generation of the <filename>extras.o</filename> file, the startup code
and the linker script actually happens via &make; custom build steps,
typically defined in appropriate HAL packages. The component framework
has no special knowledge of these targets.
</para>
<para>
By default custom build steps for a &make-object; property happen
during the same phase as most compilations, but this can be changed
using a <literal>-priority</literal> option. Similarly custom build
steps for a &make; property happen at the end of a build, but this can
also be changed with a <literal>-priority</literal> 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.
</para>
<para>
Some build systems may run several commands of the same priority in
parallel. For example files listed in &compile; properties may get
compiled in parallel, concurrently with &make-object; custom build
steps with default priorities. Since most of the time for an &eCos;
build involves processing &compile; 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.
</para>

<!-- }}} -->
<!-- {{{ Update                 -->

<sect2 id="build.make.update">
<title>Updating the Build Tree</title>

<para>
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
<filename>ecos.ecc</filename>. 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
<literal>--enable-maintainer-mode</literal> option provide by the
<application class="software">autoconf</application> and <application
class="software">automake</application> programs. At present no &eCos;
build system implements this functionality, but it is likely to be
added in a future release.
</para>

</sect2>

<!-- }}} -->
<!-- {{{ Exporting headers      -->

<sect2 id="build.make.export">
<title>Exporting Public Header Files</title>

<para>
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 <literal>-I</literal> 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 <filename
class="directory">include</filename> subdirectory of the install tree.
The process involves the following:
</para>

<orderedlist>
<listitem>
<para>
The install tree, for example <filename
class="directory">/usr/local/ecos/install</filename>, and its <filename
class="directory">include</filename> subdirectory <filename
class="directory">/usr/local/ecos/install/include</filename> will typically be
created when the build tree is generated or updated. At the same time
configuration header files will be written to the <filename
class="directory">pkgconf</filename> subdirectory, for example
<filename
class="directory">/usr/local/ecos/include/pkgconf</filename>, 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.
</para>
</listitem>
<listitem>
<para>
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.
</para>
<orderedlist>
<listitem>
<para>
If the package has an <link
linkend="ref.include-files">&include-files;</link> property then this
lists all the exported header files:
</para>
<programlisting width=72>
cdl_package &lt;some_package&gt; {
    &hellip;
    include_files header1.h header2.h
}    
</programlisting>
<para>
If no arguments are given then the package does not export any header
files.
</para>
<programlisting width=72>
cdl_package &lt;some_package&gt; {
    &hellip;
    include_files
}    
</programlisting>
<para>
The listed files may be in an <filename
class="directory">include</filename> subdirectory within the package's
hierarchy, or they may be relative to the package's toplevel
directory. The &include-files; property is intended mainly for very
simple packages. It can also be useful when converting existing code