package.sgml

ecos实时嵌入式操作系统

</para>
<para>
Very occasionally the inability of one package to see implementation
details of another does cause problems. One example occurs in HAL
packages, where it may be desirable for the architectural, variant and
platform HAL's to share some information that should not be visible to
other packages or to application code. This may be addressed in the
future by introducing the concept of <literal>friend</literal>
packages, just as a C++ class can have <literal>friend</literal>
functions and classes which are allowed special access to a class
internals. It is not yet clear whether such cases are sufficiently
frequent to warrant introducing such a facility.
</para>
</sect3>

<sect3 id="package.source.config">
<title>Source Code and Configuration Options</title>
<para>
Configurability usually involves source code that needs to implement
different behavior depending on the settings of configuration
options. It is possible to write packages where the only consequence
associated with various configuration options is to control what gets
built, but this approach is limited and does not allow for
fine-grained configurability. There are three main ways in which
options could affect source code at build time:
</para>

<orderedlist>
<listitem>
<para>
The component code can be passed through a suitable preprocessor,
either an existing one such as <application
class="software">m4</application> or a new one specially designed with
configurability in mind. The original sources would reside in the
component repository and the processed sources would reside in the
build tree. These processed sources can then be compiled in the usual
way.
</para>
<para>
This approach has two main advantages. First, it is independent from
the programming language used to code the components, provided
reasonable precautions are taken to avoid syntax clashes between
preprocessor statements and actual code. This would make it easier in
future to support languages other than C and C++. Second, configurable
code can make use of advanced preprocessing facilities such as loops
and recursion. The disadvantage is that component writers would have
to learn about a new preprocessor and embed appropriate directives in
the code. This makes it much more difficult to turn existing code into
components, and it involves extra training costs for the component
writers.
</para>
</listitem>
<listitem>
<para>
Compiler optimizations can be used to elide code that should not be
present, for example:
</para>
<programlisting width=72>
    &hellip;
    if (CYGHWR_NUMBER_UARTS &gt; 0) {
        &hellip;
     }
    &hellip;
</programlisting>
<para>
If the compiler knows that <varname>CYGHWR_NUMBER_UARTS</varname> is
the constant number 0 then it is a trivial operation to get rid of the
unnecessary code. The component framework still has to define this
symbol in a way that is acceptable to the compiler, typically by using
a <literal>const</literal> variable or a preprocessor symbol. In some
respects this is a clean approach to configurability, but it has
limitations. It cannot be used in the declarations of data structures
or classes, nor does it provide control over entire functions. In
addition it may not be immediately obvious that this code is affected
by configuration options, which may make it more difficult to
understand.
</para>
</listitem>
<listitem>
<para>
Existing language preprocessors can be used. In the case of C or C++
this would be the standard C preprocessor, and configurable code would
contain a number of <literal>#ifdef</literal> and
<literal>#if</literal> statements.
</para>
<programlisting width=72>
#if (CYGHWR_NUMBER_UARTS &gt; 0)
     &hellip;
#endif
</programlisting>
<para>
This approach has the big advantage that the C preprocessor is a
technology that is both well-understood and widely used. There are
also disadvantages: it is not directly applicable to components
written in other languages such as Java (although it is possible to
use the C preprocessor as a stand-alone program); the preprocessing
facilities are rather limited, for example there is no looping
facility; and some people consider the technology to be ugly. Of
course it may be possible to get around the second objection by
extending the preprocessor that is used by gcc and g++.
</para>
</listitem>
</orderedlist>

<para>
The current component framework generates configuration header files
with C preprocessor <literal>#define's</literal> for each option
(typically, there various properties which can be used to control
this). It is up to component writers to decide whether to use
preprocessor <literal>#ifdef</literal> statements or language
constructs such as <literal>if</literal>. At present there is no
support for languages which do not involve the C preprocessor,
although such support can be added in future when the need arises.
</para>

</sect3>


</sect2>

<!-- }}} -->
<!-- {{{ Headers                -->

<sect2 id="package.headers">
<title>Exported Header Files</title>

<para>
A package's exported header files should specify the interface
provided by that package, and avoid any implementation details.
However there may be performance or other reasons why implementation
details occasionally need to be present in the exported headers.
</para>

<note>
<para>
Not all programming languages have the concept of a header file. In
some cases the component framework would need extensions to support
packages written in such languages. 
</para>
</note>

<para>
Configurability has a number of effects on the way exported header
files should be written. There may be configuration options which
affect the interface of a package, not just the implementation. It is
necessary to worry about nested <literal>#include's</literal> and how
this affects package and application builds. A special case of this
relates to whether or not exported header files should
<literal>#include</literal> configuration headers. These configuration
headers are exported, but should only be <literal>#include'd</literal>
when necessary.
</para>

<sect3 id="package.headers.functions">
<title>Configurable Functionality</title>

<para>
Many configuration options affect only the implementation of a
package, not the interface. However some options will affect the
interface as well, which means that the options have to be tested in
the exported header files. Some implementation choices, for example
whether or not a particular function should be inlined, also need to
be tested in the header file because of language limitations.
</para>
<para>
Consider a configuration option
<varname>CYGFUN_KERNEL_MUTEX_TIMEDLOCK</varname> which controls
whether or not a function <function>cyg_mutex_timedlock</function> is
provided. The exported kernel header file <filename
class="headerfile">cyg/kernel/kapi.h</filename> could contain the
following:
</para>

<programlisting width=72>
#include &lt;pkgconf/kernel.h&gt;
&hellip;
#ifdef CYGFUN_KERNEL_MUTEX_TIMEDLOCK
extern bool cyg_mutex_timedlock(cyg_mutex_t*);
#endif
</programlisting>

<para>
This is a correct header file, in that it defines the exact interface
provided by the package at all times. However is has a number of
implications. First, the header file is now dependent on <filename
class="headerfile">pkgconf/kernel.h</filename>, so any changes to
kernel configuration options will cause <filename
class="headerfile">cyg/kernel/kapi.h</filename> to be out of date, and
any source files that use the kernel interface will need rebuilding.
This may affect sources in the kernel package, in other packages, and
in application source code. Second, if the application makes use of
this function somewhere but the application developer has
misconfigured the system and disabled this functionality anyway then
there will now be a compile-time error when building the application.
Note that other packages should not be affected, since they should
impose appropriate constraints on
<varname>CYGFUN_KERNEL_MUTEX_TIMEDLOCK</varname> if they use that
functionality (although of course some dependencies like this may get
missed by component developers).
</para>
<para>
An alternative approach would be:
</para>

<programlisting width=72>
extern bool cyg_mutex_timedlock(cyg_mutex_t*);
</programlisting>

<para>
Effectively the header file is now lying about the functionality
provided by the package. The first result is that there is no longer a
dependency on the kernel configuration header. The second result is
that an application file using the timed-lock function will now
compile, but the application will fail to link. At this stage the
application developer still has to intervene, change the
configuration, and rebuild the system. However no application
recompilations are necessary, just a relink.
</para>

<para>
Theoretically it would be possible for a tool to analyze linker errors
and suggest possible configuration changes that would resolve the
problem, reducing the burden on the application developer. No such
tool is planned in the short term.
</para>

<para>
It is up to component writers to decide which of these two approaches
should be preferred. Note that it is not always possible to avoid
<literal>#include'ing</literal> a configuration header file in an
exported one, for example an option may affect a data structure rather
than just the presence or absence of a function. Issues like this will
vary from package to package.
</para>

</sect3>

<sect3 id="package.headers.includes">
<title>Nested <literal>#include's</literal></title>
<para>
As a general rule, unnecessary <literal>#include's</literal> should be
avoided. A header file should <literal>#include</literal> only those
header files which are absolutely needed for it to define its
interface. Any additional <literal>#include's</literal> make it more
likely that package or application source files become dependent on
configuration header files and will get rebuilt unnecessarily when
there are minor configuration changes.
</para>
</sect3>

<sect3 id="package.headers.configincludes">
<title>Including Configuration Headers</title>
<para>
Exported header files should avoid <literal>#include'ing</literal>
configuration header files unless absolutely necessary, to avoid
unnecessary rebuilding of both application code and other packages
when there are minor configuration changes. A
<literal>#include</literal> is needed only when a configuration option
affects the exported interface, or when it affects some implementation
details which is controlled by the header file such as whether or not
a particular function gets inlined.
</para>
<para>
There are a couple of ways in which the problem of unnecessary
rebuilding could be addressed. The first would require more
intelligent handling of header file dependency handling by the tools
(especially the compiler) and the build system. This would require
changes to various non-eCos tools. An alternative approach would be to
support finer-grained configuration header files, for example there
could be a file <filename
class="headerfile">pkgconf/libc/inline.h</filename> controlling which
functions should be inlined. This could be achieved by some fairly
simple extensions to the component framework, but it makes it more
difficult to get the package header files and source code correct:
a C preprocessor <literal>#ifdef</literal> directive does not
distinguish between a symbol not being defined because the option is
disabled, or the symbol not being defined because the appropriate
configuration header file has not been <literal>#include'd</literal>.
It is likely that a cross-referencing tool would have to be developed
first to catch problems like this, before the component framework
could support finer-grained configuration headers.
</para>
</sect3>

</sect2>

<!-- }}} -->
<!-- {{{ Documentation          -->

<sect2 id="package.documentation">
<title>Package Documentation</title>
<para>
On-line package documentation should be in HTML format. The component
framework imposes no special limitations: component writers can decide
which version of the HTML specification should be followed; they can
also decide on how best to cope with the limitations of different
browsers. In general it is a good idea to keep things simple.
</para>
</sect2>

<!-- }}} -->
<!-- {{{ Tests                  -->

<sect2 id="package.tests">
<title>Test Cases</title>
<para>
Packages should normally come with one or more test cases. This allows
application developers to verify that a given package works correctly
on their particular hardware and in their particular configuration,
making it slightly more likely that they will attempt to find bugs in
their own code rather than automatically blaming the component
writers.
</para>
<para>
At the time of writing the application developer support for building
and running test cases via the component framework is under review and
likely to change. Currently each test case should consist of a single