package.sgml

ecos实时嵌入式操作系统

<para>
A typical package contains the following:
</para>
<orderedlist>
<listitem>
<para>
Some number of source files which will end up in a library. The
application code will be linked with this library to produce an
executable. Some source files may serve other purposes, for example to
provide a linker script.
</para>
</listitem>
<listitem>
<para>
Exported header files which define the interface provided by the
package. 
</para>
</listitem>
<listitem>
<para>
On-line documentation, for example reference pages for each exported
function. 
</para>
</listitem>
<listitem>
<para>
Some number of test cases, shipped in source format, allowing users to
check that the package is working as expected on their particular
hardware and in their specific configuration.
</para>
</listitem>
<listitem>
<para>
One or more &CDL; scripts describing the package to the configuration
system.
</para>
</listitem>
</orderedlist>
<para>
It is also conventional to have a per-package
<filename>ChangeLog</filename> file used to keep track of changes to
that package. This is especially valuable to end users of the package
who may not have convenient access to the source code control system
used to manage the master copy of the package, and hence cannot find
out easily what has changed. Often it can be very useful to the main
developers as well.
</para>
<para>
Any given packages need not contain all of these. It is compulsory to
have at least one &CDL; script describing the package, otherwise the
component framework would be unable to process it. Some packages may
not have any source code: it is possible to have a package that merely
defines a common interface which can then be implemented by several
other packages, especially in the context of device drivers; however
it is still common to have some code in such packages to avoid
replicating shareable code in all of the implementation packages.
Similarly it is possible to have a package with no exported header
files, just source code that implements an existing interface: for
example an ethernet device driver might just implement a standard
interface and not provide any additional functionality. Packages do
not need to come with any on-line documentation, although this may
affect how many people will want to use the package. Much the same
applies to per-package test cases.
</para>

<para>
The component framework has a recommended per-package directory layout
which splits the package contents on a functional basis:
</para>

<informalfigure PgWide=1>
<mediaobject>
<imageobject>
<imagedata fileref="package.png" Scalefit=1 Align="Center">
</imageobject>
</mediaobject>
</informalfigure>

<para>
For example, if a package has an <filename
class="directory">include</filename> sub-directory then the component
framework will assume that all header files in and below that
directory are exported header files and will do the right thing at
build time. Similarly if there is &doc; property indicating the
location of on-line documentation then the component framework will
first look in the <filename class="directory">doc</filename>
sub-directory.
</para>

<para>
This directory layout is just a guideline, it is not enforced by the
component framework. For simple packages it often makes more sense to
have all of the files in just one directory. For example a package
could just contain the files <filename>hello.cxx</filename>,
<filename>hello.h</filename>, <filename>hello.html</filename> and
<filename>hello.cdl</filename>. By default
<filename>hello.h</filename> will be treated as an exported header
file, although this can be overridden with the <link
linkend="ref.include-files">&include-files;</link> property. Assuming
there is a &doc; property referring to <filename>hello.html</filename>
and there is no <filename class="directory">doc</filename>
sub-directory then the tools will search for this file relative to the
package's top-level and everything will just work. Much the same
applies to <filename>hello.cxx</filename> and
<filename>hello.cdl</filename>. 
</para>

<tip>
<para>
Older versions of the &eCos; build system only supported packages that
followed the directory structure exactly. Hence certain core packages
such as <filename>error</filename> implement the full directory
structure, even though that is a particularly simple package and the
full directory structure is inappropriate. Component writers can
decide for themselves whether or not the directory structure
guidelines are appropriate for their package.
</para>
</tip>

<!-- }}} -->
<!-- {{{ Build process          -->

<sect2 id="package.build">
<title>Outline of the Build Process</title>
<para>
The full build process is described in <xref linkend="build">, but 
a summary is appropriate here. A build involves three directory
structures: 
</para>

<orderedlist>
<listitem>
<para>
The component repository. This is where all the package source code is
held, along with &CDL; scripts, documentation, and so on. For build
purposes a component repository is read-only. Application developers
will only modify the component repository when installing or removing
packages, via the administration tool. Component writers will
typically work on just one package in the component repository.
</para>
</listitem>
<listitem>
<para>
The build tree. Each configuration has its own build tree, which can
be regenerated at any time using the configuration's
<filename>ecos.ecc</filename> savefile. The build tree contains only
intermediate files, primarily object files. Once a build is complete
the build tree contains no information that is useful for application
development and can be wiped, although this would slow down any
rebuilds following changes to the configuration.
</para>
</listitem>
<listitem>
<para>
The install tree. This is populated during a build, and contains all
the files relevant to application development. There will be a
<filename class="directory">lib</filename> sub-directory which
typically contains <filename>libtarget.a</filename>, a linker script,
start-up code, and so on. There will also be an <filename
class="directory">include</filename> sub-directory containing all the
header files exported by the various packages. There will also be a
<filename class="directory">include/pkgconf</filename> sub-directory
containing various configuration header files with
<literal>#define's</literal> for the options. Typically the install
tree is created within the build tree, but this is not a requirement.
</para>
</listitem>
</orderedlist>

<para>
The build process involves the following steps:
</para>
<orderedlist>
<listitem>
<para>
Given a configuration, the component framework is responsible for
creating all the directories in the build and install trees. If these
trees already exist then the component framework is responsible for
any clean-ups that may be necessary, for example if a package has been
removed then all related files should be expunged from the build and
install trees. The configuration header files will be generated at
this time. Depending on the host environment, the component framework
will also generate makefiles or some other way of building the various
packages. Every time the configuration is modified this step needs to
be repeated, to ensure that all option consequences take effect. Care
is taken that this will not result in unnecessary rebuilds.
</para>
<note>
<para>
At present this step needs to be invoked manually. In a future version
the generated makefile may if desired perform this step automatically,
using a dependency on the <filename>ecos.ecc</filename> savefile.
</para>
</note>
</listitem>
<listitem>
<para>
The first step in an actual build is to make sure that the install
tree contains all exported header files. All compilations will use
the install tree's <filename class="directory">include</filename>
directory as one of the places to search for header files.
</para>
</listitem>
<listitem>
<para>
All source files relevant to the current configuration get compiled.
This involves a set of compiler flags initialized on a per-target
basis, with each package being able to modify these flags, and with
the ability for the user to override the flags as well. Care has to be
taken here to avoid inappropriate target-dependencies in packages that
are intended to be portable. The component framework has built-in
knowledge of how to handle C, C++ and assembler source files &mdash;
other languages may be added in future, as and when necessary. The
<link linkend="ref.compile">&compile;</link> property is used to
list the files that should get compiled. All object files end up in
the build tree.
</para>
</listitem>
<listitem>
<para>
Once all the object files have been built they are collected into a
library, typically <filename>libtarget.a</filename>, which can then be
linked with application code. The library is generated in the install
tree. 
</para>
</listitem>
<listitem>
<para>
The component framework provides support for custom build steps, using
the <link linkend="ref.make-object">&make-object;</link> and
<link linkend="ref.make">&make;</link> properties. The results of
these custom build steps can either be object files that should end up
in a library, or other files such as a linker script. It is possible
to control the order in which these custom build steps take place, for
example it is possible to run a particular build step before any of
the compilations happen.
</para>
</listitem>
</orderedlist>

</sect2>

<!-- }}} -->
<!-- {{{ Sources                -->

<sect2 id="package.source">
<title>Configurable Source Code</title>
<para>
All packages should be totally portable to all target hardware (with
the obvious exceptions of HAL and device driver packages). They should
also be totally bug-free, require the absolute minimum amount of code
and data space, be so efficient that cpu time usage is negligible, and
provide lots of configuration options so that application developers
have full control over the behavior. The configuration options are
optional only if a package can meet the requirements of every
potential application without any overheads. It is not the purpose of
this guide to explain how to achieve all of these requirements.
</para>
<para>
The &eCos; component framework does have some important implications
for the source code: compiler flag dependencies; package interfaces
vs. implementations; and how configuration options affect source code.
</para>

<sect3 id="package.source.flags">
<title>Compiler Flag Dependencies</title>
<para>
Wherever possible component writers should avoid dependencies on
particular compiler flags. Any such dependencies are likely to impact
portability. For example, if one package needs to be built in
big-endian mode and another package needs to be built in little-endian
mode then usually it will not be possible for application developers
to use both packages at the same time; in addition the application
developer is no longer given a choice in the matter. It is far better
for the package source code to adapt the endianness at compile-time,
or possibly at run-time although that will involve code-size
overheads.
</para>
<note>
<para>
A related issue is that the current support for handling compiler
flags in the component framework is still limited and incapable of
handling flags at a very fine-grain. The support is likely to be
enhanced in future versions of the framework, but there are
non-trivial problems to be resolved.
</para>
</note>
</sect3>

<sect3 id="package.source.interfaces">
<title>Package Interfaces and Implementations</title>
<para>
The component framework provides encapsulation at the package level. A
package <literal>A</literal> has no way of accessing the
implementation details of another package <literal>B</literal> at
compile-time. In particular, if there is a private header file
somewhere in a package's <filename class="directory">src</filename>
sub-directory then this header file is completely invisible to other
packages. Any attempts to cheat by using relative pathnames beginning
with <filename class="directory">../..</filename> are generally doomed
to failure because of the presence of package version directories.
There are two ways in which one package can affect another: by means
of the exported header files, which define a public interface; or via
the &CDL; scripts.
</para>
<para>
This encapsulation is a deliberate aspect of the overall &eCos;
component framework design. In most cases it does not cause any
problems for component writers. In some cases enforcing a clean
separation between interface and implementation details can improve
the code. Also it reduces problems when a package gets upgraded:
component writers are free to do pretty much anything on the
implementation side, including renaming every single source file; care
has to be taken only with the exported header files and with the &CDL;
data, because those have the potential of impacting other packages.
Application code is similarly unable to access package implementation
details, only the exported interface.