package.sgml

ecos实时嵌入式操作系统

<!-- {{{ Banner                 -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     package.sgml                                                -->
<!--                                                                 -->
<!--     How to write a package.                                     -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####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="package">
<title>Package Organization</title>

<!-- {{{ Introit                -->

<para>
For a package to be usable in the &eCos; component framework it must
conform to certain rules imposed by that framework. Packages must be
distributed in a form that is understood by the component repository
administration tool. There must be a top-level &CDL; script which
describes the package to the component framework. There are certain
limitations related to how a package gets built, so that the package
can still be used in a variety of host environments. In addition to
these rules, the component framework provides a number of guidelines.
Packages do not have to conform to the guidelines, but sticking to
them can simplify certain operations.
</para>
<para>
This chapter deals with the general organization of a package, for
example how to distinguish between private and exported header files.
<xref linkend="language"> describes the &CDL; language.
<xref linkend="build"> details the build process.
</para>

<!-- }}} -->
<!-- {{{ Repository             -->

<sect1 id="package.hierarchy">
<title>Packages and the Component Repository</title>

<para>
All &eCos; installations include a component repository. This is a
directory structure for all installed packages. The component
framework comes with an administration tool that allows new packages
or new versions of a package to be installed, old packages to be
removed, and so on. The component repository includes a simple
database, maintained by the administration tool, which contains
details of the various packages.
</para>

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

<para>
Each package has its own little directory hierarchy within the
component repository. Keeping several packages in a single directory
is illegal. The error, infra and kernel packages all live at the
top-level of the repository. For other types of packages there are
some pre-defined directories: <filename
class="directory">compat</filename> is used for compatibility
packages, which implement other interfaces such as &uITRON; or POSIX
using native &eCos; calls; <filename class="directory">hal</filename>
is used for packages that port &eCos; to different architectures or
platforms, and this directory is further organized on a
per-architecture basis; <filename class="directory">io</filename> is
intended for device drivers; <filename
class="directory">language</filename> is used for language support
libraries, for example the C library. There are no strict rules
defining where new packages should get installed. Obviously if an
existing top-level directory such as <filename
class="directory">compat</filename> is applicable then the new package
should go in there. If a new category is desirable then it is possible
to create a new sub-directory in the component repository. For
example, an organization planning to release a number of &eCos;
packages may want them all to appear below a sub-directory
corresponding to the organization's name&nbsp;&mdash; in the hope that
the name will not change too often. It is possible to add new packages
directly to the top-level of the component repository, but this should
be avoided.
</para>

<para>
The <database>ecos.db</database> file holds the component repository
database and is managed by the administration tool. The various
configuration tools read in this file when they start-up to obtain
information about the various packages that have been installed. When
developing a new package it is necessary to add some information to
the file, as described in <xref linkend="language.database">. The
<filename class="directory">templates</filename> directory holds
various configuration templates.
</para>

<note>
<para>
Earlier releases of &eCos; came with two separate files,
<filename>targets</filename> and <filename>packages</filename>. The
<database>ecos.db</database> database replaces both of these.
</para>
</note>

<caution>
<para>
The current <database>ecos.db</database> database does not yet provide
all of the information needed by the component framework. Its format
is subject to change in future releases, and the file may be replaced
completely if necessary. There are a number of other likely future
developments related to the component repository and the database. The
way targets are described is subject to change. Sometimes it is
desirable for component writers to do their initial development in a
directory outside the component repository, but there is no specific
support in the framework for that yet.
</para>
</caution>

</sect1>

<!-- }}} -->
<!-- {{{ Versioning             -->

<sect1 id="package.versions">
<title>Package Versioning</title>
<para>
Below each package directory there can be one or more version
sub-directories, named after the versions. This is a requirement of
the component framework: it must be possible for users to install
multiple versions of a package and select which one to use for any
given application. This has a number of advantages to users: most
importantly it allows a single component repository to be shared
between multiple users and multiple projects, as required; also it
facilitates experiments, for example it is relatively easy to try out
the latest version of some package and see if it makes any difference.
There is a potential disadvantage in terms of disk space. However
since &eCos; packages generally consist of source code intended for
small embedded systems, and given typical modern disk sizes, keeping a
number of different versions of a package installed will usually be
acceptable. The administration tool can be used to remove versions
that are no longer required.
</para>

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

<para>
The version <filename>current</filename> is special. Typically it
corresponds to the very latest version of the sources, obtained by
anonymous &CVS;. These sources may change frequently, unlike full
releases which do not change (or only when patches are produced).
Component writers may also want to work on the
<filename>current</filename> version.
</para>
<para>
All other subdirectories of a package correspond to specific releases
of that package. The component framework allows users to select the
particular version of a package they want to use, but by default the
most recent one will be used. This requires some rules for ordering
version numbers, a difficult task because of the wide variety of ways
in which versions can be identified.
</para>

<orderedlist>
<listitem>
<para>
The version <filename>current</filename> is always considered to be
the most recent version.
</para
</listitem>

<listitem>
<para>
If the first character of both strings are either <literal>v</literal>
or <literal>V</literal>, these are skipped because it makes little
sense to enforce case sensitivity here. Potentially this could result
in ambiguity if there are two version directories
<literal>V1.0</literal> and <literal>v1.0</literal>, but this will
match the confusion experienced by any users of such a package.
However if two subsequent releases are called <literal>V1.0</literal>
and <literal>v1.1</literal>, e.g. because of a minor mix-up when
making the distribution file, then the case difference is ignored.
</para>
</listitem>

<listitem>
<para>
Next the two version strings are compared one character at a time.
If both strings are currently at a digit then a string to number
conversion takes place, and the resulting numbers are compared.
For example <literal>v10</literal> is a more recent release than
<literal>v2</literal>. If the two numbers are the same then processing
continues, so for <literal>v2b</literal> and <literal>v2c</literal>
the version comparison code would move on to <literal>b</literal> and
<literal>c</literal>. 
</para>
</listitem>

<listitem>
<para>
The characters dot <literal>.</literal>, hyphen <literal>-</literal>
and underscore <literal>_</literal> are treated as equivalent
separators, so if one release goes out as <literal>v1_1</literal> and
the next goes out as <literal>v1.2</literal> the separator has no
effect.
</para>
</listitem>

<listitem>
<para>
If neither string has yet terminated but the characters are different,
ASCII comparison is used. For example <literal>V1.1b</literal> is
more recent than <literal>v1.1alpha</literal>.
</para>
</listitem>

<listitem>
<para>
If one version string terminates before the other, the current
character determines which is the more recent. If the other string is
currently at a separator character, for example
<literal>v1.3.1</literal> and <literal>v1.3</literal>, then the former
is assumed to be a minor release and hence more recent than the
latter. If the other string is not at a separator character, for
example <literal>v1.3beta</literal>, then it is treated as an
experimental version of the <literal>v1.3</literal> release and hence
older. 
</para>
</listitem>

<listitem>
<para>
There is no special processing of dates, so with two versions
<literal>ss-20000316</literal> and <literal>ss-20001111</literal>
the numerical values <literal>20001111</literal> and
<literal>20000316</literal> determine the result: larger values are
more recent. It is suggested that the full year be used in such cases
rather than a shorthand like <literal>00</literal>, to avoid
Y2100 problems.
</para>
</listitem>

<listitem>
<para>
There is no limit on how many levels of versioning are used, so
there could in theory be a <literal>v3.1.4.1.5.9.2.7</literal> release
of a package. However this is unlikely to be of benefit to typical
users of a package.
</para>
</listitem>

</orderedlist>

<para>
The version comparison rules of the component framework may not be
suitable for every version numbering scheme in existence, but they
should cope with many common cases.
</para>

<caution>
<para>
There are some issues still to be resolved before it is possible to
combine the <filename>current</filename> sources available via
anonymous &CVS and full releases of &eCos; and additional packages in
a single component repository. The first problem relates to the
<database>ecos.db</database> database: if a new package is added via
the CVS repository then this requires a database update, but the
administration tool is bypassed. The second problem arises if an
organization chooses to place its component repository under source
code control using &CVS;, in which case different directories will
belong to different &CVS; servers. These issues will be addressed in a
future release.
</para>
</caution>

</sect1>

<!-- }}} -->
<!-- {{{ Package contents       -->

<!-- {{{ Introit                -->

<sect1 id="package.contents">
<title>Package Contents and Layout</title>