build.sgml

ecos实时嵌入式操作系统

<!-- {{{ Banner         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     build.sgml                                                  -->
<!--                                                                 -->
<!--     Description of the build system.                            -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 2000, 2001, 2002 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 obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!--                                                                 -->      
<!-- ####COPYRIGHTEND####                                            -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- Author(s):   bartv                                              -->
<!-- Contact(s):  bartv                                              -->
<!-- Date:        2000/02/06                                         -->
<!-- Version:     0.01                                               -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<chapter id="build">
<title>The Build Process</title>

<!-- {{{ Introit                -->

<para>
Some &CDL; properties describe the consequences of manipulating
configuration options. There are two main types of consequences.
Typically enabling a configuration option results in one or more
<literal>#define's</literal> in a configuration header file, and
properties that affect this include &define;, &define-proc; and
&no-define;. Enabling a configuration option can also affect the build
process, primarily determining which files get built and added to the
appropriate library. Properties related to the build process include
&compile; and &make;. This chapter describes the whole build process,
including details such as compiler flags and custom build steps.
</para>
<para>
Part of the overall design of the &eCos; component framework is that
it can interact with a number of different build systems. The most
obvious of these is <application class="software">GNU
make</application>:the component framework can generate one or more
makefiles, and the user can then build the various packages simply by
invoking <application class="software">make</application>. However it
should also be possible to build &eCos; by other means: the
component framework can be queried about what is involved in building
a given configuration, and this information can then be fed into the
desired build system. Component writers should be aware of this
possibility. Most packages will not be affected because the &compile;
property can be used to provide all the required information, but care
has to be taken when writing custom build steps.
</para>

<!-- }}} -->
<!-- {{{ Build Tree Generation  -->

<sect1 id="build.outline">
<title>Build Tree Generation</title>

<para>
It is necessary to create an &eCos; configuration before anything can
be built. With some tools such as the graphical configuration tool
this configuration will be created in memory, and it is not essential
to produce an <filename>ecos.ecc</filename> savefile first (although
it is still very desirable to generate such a savefile at some point,
to allow the configuration to be re-loaded later on). With other tools
the savefile is generated first, for example using
<literal>ecosconfig&nbsp;new</literal>, and then a build tree is
generated using <literal>ecosconfig&nbsp;tree</literal>. The savefile
contains all the information needed to recreate a configuration.
</para>
<para>
An &eCos; build actually involves three separate trees. The component
repository acts as the source tree, and for application developers
this should be considered a read-only resource. The build tree is
where all intermediate files, especially object files, are created.
The install tree is where the main library
<filename>libtarget.a</filename>, the exported header files, and
similar files end up. Following a successful build it is possible to
take just the install tree and use it for developing an application:
none of the files in the component repository or the build tree are
needed for that. The build tree will be needed again only if the user
changes the configuration. However the install tree does not contain
copies of all of the documentation for the various packages, instead
the documentation is kept only in the component repository.
</para>
<para>
By default the build tree, the install tree, and the
<filename>ecos.ecc</filename> savefile all reside in the same
directory tree. This is not a requirement, both the install tree and
the savefile can be anywhere in the file system.
</para>
<para>
It is worth noting that the component framework does not separate the
usual <literal>make</literal> and <literal>make&nbsp;install</literal>
stages. A build always populates the install tree, and any
<literal>make&nbsp;install</literal> step would be redundant.
</para>
<para>
The install tree will always begin with two directories, <filename
class="directory">include</filename> for the exported header files and
<filename class="directory">lib</filename> for the main library
<filename class="directory">libtarget.a</filename> and other files
such as the linker script. In addition there will be a subdirectory
<filename class="directory">include/pkgconf</filename> containing the
configuration header files, which are generated or updated at the same
time the build tree is created or updated. More details of header file
generation are given below. Additional <filename
class="directory">include</filename> subdirectories such as <filename
class="directory">sys</filename> and <filename
class="directory">cyg/kernel</filename> will be created during the
first build, when each package's exported header files are copied to
the install tree. The install tree may also end up with additional
subdirectories during a build, for example as a result of custom build
steps. 
</para>
<para>
The component framework does not define the structure of the build
tree, and this may vary between build systems. It can be assumed that
each package in the configuration will have its own directory in the
build tree, and that this directory will be used for storing the
package's object files and as the current directory for any build
steps for that package. This avoids problems when custom build steps
from different packages generate intermediate files which happen to
have the same name.
</para>
<para>
Some build systems may allow application developers to copy a source
file from the component repository to the build tree and edit the
copy. This allows users to experiment with small changes, for example
to add a couple of lines of debugging to a package, without having to
modify the master copy in the component repository which could be
shared by several projects or several people. Functionality such as
this is transparent to component writers, and it is the responsibility
of the build system to make sure that the right thing happens.
</para>

<note>
<para>
There are some unresolved issues related to the build tree and install
tree. Specifically, when updating an existing build or install tree,
what should happen to unexpected files or directories? Suppose the
user started with a configuration that included the math library, and
the install tree contains header files <filename
class="headerfile">include/math.h</filename> and <filename
class="headerfile">include/sys/ieeefp.h</filename>. The user then removed
the math library from the configuration and is updating the build
tree. It is now desirable to remove these header files from the
install tree, so that if any application code still attempts to use
the math library this will fail at compile time rather than at link
time. There will also be some object files in the existing
<literal>libtarget.a</literal> library which are no longer
appropriate, and there may be other files in the install tree as a
result of custom build steps. The build tree will still contain a
directory for the math library, which no longer serves any purpose.
</para>
<para>
However, it is also possible that some of the files in the build tree
or the install tree were placed there by the user, in which case
removing them automatically would be a bad idea.
</para>
<para>
At present the component framework does not keep track of exactly what
should be present in the build and install trees, so it cannot readily
determine which files or library members are obsolete and can safely
be removed, and which ones are unexpected and need to be reported to
the user. This will be addressed in a future release of the system.
</para>
</note>

</sect1>

<!-- }}} -->
<!-- {{{ Header File Generation -->

<sect1 id="build.headers">
<title>Configuration Header File Generation</title>

<para>
Configuration options can affect a build in two main ways. First,
enabling a configuration option or other &CDL; entity can result in
various files being built and added to a library, thus providing
functionality to the application code. However this mechanism can only
operate at a rather coarse grain, at the level of entire source files.
Hence the component framework also generates configuration header
files containing mainly C preprocessor <literal>#define</literal>
directives. Package source code can then <literal>#include</literal>
the appropriate header files and use <literal>#if</literal>,
<literal>#ifdef</literal> and <literal>#ifndef</literal> directives to
adapt accordingly. In this way configuration options can be used to
enable or disable entire functions within a source file or just a
single line, whichever is appropriate.
</para>
<para>
The configuration header files end up in the <filename
class="directory">include/pkgconf</filename> subdirectory of the
install tree. There will be one header file for the system as a whole,
<filename class="headerfile">pkgconf/system.h</filename>, and there will
be additional header files for each package, for example
<filename class="headerfile">pkgconf/kernel.h</filename>. The header files
are generated when creating or updating the build and install trees,
which needs to happen after every change to the configuration.
</para>
<para>
The component framework processes each package in the configuration
one at a time. The exact order in which the packages are processed is
not defined, so the order in which <literal>#define's</literal> will
end up in the global <filename
class="headerfile">pkgconf/system.h</filename> header may vary. However
for any given configuration the order should remain consistent until
packages are added to or removed from the system. This avoids
unnecessary changes to the global header file and hence unnecessary
rebuilds of the packages and of application code because of header
file dependency handling.
</para>
<para>
Within a given package the various components, options and interfaces
will be processed in the order in which they were defined in the
corresponding &CDL; scripts. Typically the data in the configuration
headers consists only of a sequence of <literal>#define's</literal> so
the order in which these are generated is irrelevant, but some
properties such as &define-proc; can be used to add arbitrary data to
a configuration header and hence there may be dependencies on the
order. It should be noted that re-parenting an option below some other
package has no effect on which header file will contain the
corresponding <literal>#define</literal>: the preprocessor directives
will always end up in the header file for the package that defines the
option, or in the global configuration header.
</para>
<para>
There are six properties which affect the process of generating header
files:
<link linkend="ref.define-header">&define-header;</link>,
<link linkend="ref.no-define">&no-define;</link>,
<link linkend="ref.define-format">&define-format;</link>,
<link linkend="ref.define">&define;</link>,
<link linkend="ref.if-define">&if-define;</link>, and
<link linkend="ref.define-proc">&define-proc;</link>.
</para>
<para>
The &define-header; property can only occur in the body of a
&cdl-package; command and specifies the name of the header file which
should contain the package's configuration data, for example:
</para>
<programlisting width=72>
cdl_package &lt;some_package&gt; {
    &hellip;
    define_header xyzzy.h
}
</programlisting>
<para>
Given such a &define-header; property the component framework will
use the file <filename class="headerfile">pkgconf/xyzzy.h</filename> for
the package's configuration data. If a package does not have
a &define-header; property then a suitable file name is constructed
from the package's name. This involves:
</para>
<orderedlist>
<listitem>
<para>
All characters in the package name up to and including the first
underscore are removed. For example <varname>CYGPKG_KERNEL</varname>
is converted to <literal>KERNEL</literal>, and
<varname>CYGPKG_HAL_ARM</varname> is converted to
<literal>HAL_ARM</literal>.
</para>
</listitem>
<listitem>
<para>
Any upper case letters in the resulting string will be converted to
lower case, yielding e.g. <literal>kernel</literal> and
<literal>hal_arm</literal>.
</para>
</listitem>
<listitem>
<para>
A <literal>.h</literal> suffix is appended, yielding e.g.
<literal>kernel.h</literal> and <literal>hal_arm.h</literal>.
</para>
</listitem>
</orderedlist>
<para>
Because of the naming restrictions on configuration options, this
should result in a valid filename. There is a small possibility of a
file name class, for example <varname>CYGPKG_PLUGH</varname> and
<varname>CYGPKG_plugh</varname> would both end up trying to use the
same header file <filename class="headerfile">pkgconf/plugh.h</filename>,
but the use of lower case letters for package names violates the
naming conventions. It is not legal to use the &define-header;
property to put the configuration data for several packages in a
single header file. The resulting behaviour is undefined.
</para>
<para>
Once the name of the package's header file has been determined and the
file has been opened, the various components, options and interfaces
in the package will be processed starting with the package itself. The
following steps are involved:
</para>
<orderedlist>
<listitem>
<para>
If the current option or other &CDL; entity is inactive or disabled,
the option is ignored for the purposes of header file generation.
<literal>#define's</literal> are only generated for options that are
both active and enabled.
</para>
</listitem>
<listitem>