package.sgml

ecos实时嵌入式操作系统

C or C++ source file that can be compiled with the package's set of
compiler flags and linked like any application program. Each test case
should use the testing API defined by the infrastructure. A
magically-named calculated configuration option of the form
<varname>CYGPKG_&lt;PACKAGE-NAME&gt;_TESTS</varname> lists the test
cases.
</para>
</sect2>

<!-- }}} -->
<!-- {{{ Host tools             -->

<sect2 id="package.host">
<title>Host-side Support</title>
<para>
On occasion it would be useful for an &eCos; package to be shipped
with host-side support. This could take the form of an additional tool
needed to build that package. It could be an application intended to
communicate with the target-side package code and display monitoring
information. It could be a utility needed for running the package test
cases, especially in the case of device drivers. The component
framework does not yet provide any such support for host-side
software, and there are obvious issues related to portability to the
different machines that can be used for hosts. This issue may get
addressed in some future release. In some cases custom build steps can
be subverted to do things on the host side rather than the target
side, but this is not recommended.
</para>
</sect2>

<!-- }}} -->

</sect1>

<!-- }}} -->
<!-- {{{ Package Distributions  -->

<sect1 id="package.distrib">
<title>Making a Package Distribution</title>

<para>
Developers of new &eCos; packages are advised to distribute their
packages in the form of &eCos; package distribution files. Packages
distributed in this format may be added to existing &eCos; component
repositories in a robust manner using the Package Administration Tool.
This chapter describes the format of package distribution files and
details how to prepare an eCos package for distribution in this format.
</para>

<sect2 id="package.distrib.format">
<title>The &eCos; package distribution file format</title>

<para>
eCos package distribution files are gzipped GNU tar archives which
contain both the source code for one or more &eCos; packages and a
data file containing package information to be added to the component
repository database. The distribution files are subject to the
following rules:
</para>
<orderedlist numeration="Loweralpha">
<listitem>
<para>
The data file must be named <filename>pkgadd.db</filename> and must be
located in the root of the tar archive. It must contain data in a
format suitable for appending to the eCos repository database
(<database>ecos.db</database>). <xref linkend="language.database">
describes this data format. Note that a database consistency check is
performed by the &eCos; Administration Tool when
<filename>pkgadd.db</filename> has been appended to the database. Any
new target entries which refer to unknown packages will be removed at
this stage.
</para>
</listitem>
<listitem>
<para>
The package source code must be placed in one or more <filename
class="directory">&lt;package-path&gt;/&lt;version&gt;</filename>
directories in the tar archive, where each &lt;package-path&gt;
directory path is specified as the directory attribute of one of the
packages entries in <filename>pkgadd.db</filename>.
</para>
</listitem>
<listitem>
<para>
An optional license agreement file named
<filename>pkgadd.txt</filename> may be placed in the root of the tar
archive. It should contain text with a maximum line length of 79
characters. If this file exists, the contents will be presented to the
user during installation of the package. The &eCos; Package
Administration Tool will then prompt the user with the question
<prompt>"Do you accept all the terms of the preceding license
agreement?"</prompt>. The user must respond
<userinput>"yes"</userinput> to this prompt in order to proceed with
the installation.
</para>
</listitem>
<listitem>
<para>
Optional template files may be placed in one or more <filename
class="directory">templates/&lt;template_name&gt;</filename>
directories in the tar archive. Note that such template files would be
appropriate only where the packages to be distributed have a complex
dependency relationship with other packages. Typically, a third party
package can be simply added to an eCos configuration based on an
existing core template and the provision of new templates would not be
appropriate. <xref linkend="advanced.templates"> contains more
information on templates.
</para>
</listitem>
<listitem>
<para>
The distribution file must be given a <filename>.epk</filename> (not
<filename>.tar.gz</filename>) file extension. The
<filename>.epk</filename> file extension serves to distinguish &eCos;
package distributions files from generic gzipped GNU tar archives. It
also discourages users from attempting to extract the package from the
archive manually. The file browsing dialog of the &eCos; Package
Administration Tool lists only those files which have a
<filename>.epk</filename> extension.
</para>
</listitem>
<listitem>
<para>
No other files should be present in the archive.
</para>
</listitem>
<listitem>
<para>
Files in the tar archive may use <literal>LF</literal> or
<literal>CRLF</literal> line endings interchangably. The &eCos;
Administration Tool ensures that the installed files are given the
appropriate host-specific line endings.
</para>
</listitem>
<listitem>
<para>
Binary files may be placed in the archive, but the distribution of
object code is not recommended. All binary files must be given a
<literal>.bin</literal> suffix in addition to any file extension they
may already have. For example, the GIF image file
<filename>myfile.gif</filename> must be named
<filename>myfile.gif.bin</filename> in the archive. The
<filename>.bin</filename> suffix is removed during file extraction and
is used to inhibit the manipulation of line endings by the &eCos;
Administration Tool.
</para>
</listitem>
</orderedlist>
</sect2>

<sect2 id="package.distrib.prepare">
<title>Preparing eCos packages for distribution</title>

<para>
Development of new &eCos; packages or new versions of existing &eCos;
packages will take place in the context of an existing &eCos;
component repository. This section details the steps involved in
extracting new packages from a repository and generating a
corresponding &eCos; package distribution file for distribution of the
packages to other &eCos; users. The steps required are as follows:
</para>

<orderedlist numeration="Loweralpha">
<listitem>
<para>
Create a temporary directory <filename
class="directory">$PKGTMP</filename> for manipulation of the package
distribution file contents and copy the source files of the new
packages into this directory, preserving the relative path to the
package. In the case of a new package at <filename
class="directory">mypkg/current</filename> in the repository:
</para>
<screen width=72>
    $ mkdir -p $PKGTMP/mypkg
    $ cp -p -R $ECOS_REPOSITORY/mypkg/current $PKGTMP/mypkg
</screen>
<para>
Where more than one package is to be distributed in a single package
distribution file, copy each package in the above manner. Note that
multiple packages distributed in a single package distribution file
cannot be installed separately. Where such flexibility is required,
distribution of each new package in separate package distribution files
is recommended.
</para>
</listitem>
<listitem>
<para>
Copy any template files associated with the distributed packages into
the temporary directory, preserving the relative path to the template.
For example:
</para>
<screen width=72>
    $ mkdir -p $PKGTMP/templates
    $ cp -p -R $ECOS_REPOSITORY/templates/mytemplate $PKGTMP/templates
</screen>
</listitem>
<listitem>
<para>
Remove any files from the temporary directory hierarchy which you do
not want to distribute with the packages (eg object files, <filename
class="directory">CVS</filename> directories).
</para>
</listitem>
<listitem>
<para>
Add a <filename>.bin</filename> suffix to the name of any binary
files. For example, if the packages contains GIF image files (*.gif)
for documentation purposes, such files must be renamed to *.gif.bin as
follows:
</para>
<screen width=72>
   $ find $PKGTMP -type f -name '*.gif' -exec mv {} {}.bin ';'
</screen>
<para>
The <filename>.bin</filename> suffix is removed during file extraction
and is used to inhibit the manipulation of line endings by the eCos
Package Administration Tool.
</para>
</listitem>
<listitem>
<para>
Extract the package records for the new packages from the package
database file at <database>$ECOS_REPOSITORY/ecos.db</database> and
create a new file containing these records at
<filename>$PKGTMP/pkgadd.db</filename> (in the root of the temporary
directory hierarchy). Any target records which reference the
distributed packages must also be provided in pkgadd.db.
</para>
</listitem>
<listitem>
<para>
Rename the version directories under <filename
class="directory">$PKGTMP</filename> (typically <filename
class="directory">current</filename> during development) to reflect
the versions of the packages you are distributing. For example,
version 1.0 of a package may use the version directory name <filename
class="directory">v1_0</filename>:
</para>
<screen width=72>
    $ cd $PKGTMP/mypkg
    $ mv current v1_0
</screen>
<para>
<xref linkend="package.versions"> describes the version naming
conventions.
</para>
</listitem>
<listitem>
<para>
Rename any template files under <filename
class="directory">$PKGTMP</filename> (typically
<filename>current.ect</filename> during development) to reflect the
version of the template you are distributing. For example, version 1.0
of a template may use the filename <filename>v1_0.ect</filename>:
</para>
<screen width=72>
    $ cd $PKGTMP/templates/mytemplate
    $ mv current.ect v1_0.ect
</screen>
<para>
It is also important to edit the contents of the template file, changing
the version of each referenced package to match that of the packages you
are distributing. This step will eliminate version warnings during the
subsequent loading of the template.
</para>
</listitem>
<listitem>
<para>
Optionally create a licence agreement file at
<filename>$PKGTMP/pkgadd.txt</filename> containing the licensing terms
under which you are distributing the new packages. Limit each line in
this file to a maximum of 79 characters.
</para>
</listitem>
<listitem>
<para>
Create a GNU tar archive of the temporary directory hierarchy. By
convention, this archive would have a name of the form
<filename>&lt;package_name&gt;-&lt;version&gt;</filename>:
</para>
<screen width=72>
    $ cd $PKGTMP
    $ tar cf mypkg-1.0.tar *
</screen>
<para>
Note that non-GNU version of tar may create archive files which exhibit
subtle incompatibilities with GNU tar. For this reason, always use GNU
tar to create the archive file.
</para>
</listitem>
<listitem>
<para>
Compress the archive using gzip and give the resulting file a
<filename>.epk</filename> file extension:
</para>
<screen width=72>
    $ gzip mypkg-1.0.tar
    $ mv mypkg-1.0.tar.gz mypkg-1.0.epk
</screen>
<para>
The resulting eCos package distribution file (*.epk) is in a compressed
format and may be distributed without further compression.
</para>
</listitem>
</orderedlist>

</sect2>

</sect1>

<!-- }}} -->

</chapter>