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.
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:
The data file must be named pkgadd.db 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 (ecos.db). the Section called Updating the ecos.db database in Chapter 3 describes this data format. Note that a database consistency check is performed by the eCos Administration Tool when pkgadd.db has been appended to the database. Any new target entries which refer to unknown packages will be removed at this stage.
The package source code must be placed in one or more <package-path>/<version> directories in the tar archive, where each <package-path> directory path is specified as the directory attribute of one of the packages entries in pkgadd.db.
An optional license agreement file named pkgadd.txt 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 "Do you accept all the terms of the preceding license agreement?". The user must respond "yes" to this prompt in order to proceed with the installation.
Optional template files may be placed in one or more templates/<template_name> 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. the Section called Templates in Chapter 6 contains more information on templates.
The distribution file must be given a .epk (not .tar.gz) file extension. The .epk 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 .epk extension.
No other files should be present in the archive.
Files in the tar archive may use LF or CRLF line endings interchangably. The eCos Administration Tool ensures that the installed files are given the appropriate host-specific line endings.
Binary files may be placed in the archive, but the distribution of object code is not recommended. All binary files must be given a .bin suffix in addition to any file extension they may already have. For example, the GIF image file myfile.gif must be named myfile.gif.bin in the archive. The .bin suffix is removed during file extraction and is used to inhibit the manipulation of line endings by the eCos Administration Tool.
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:
Create a temporary directory $PKGTMP 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 mypkg/current in the repository:
$ mkdir -p $PKGTMP/mypkg
$ cp -p -R $ECOS_REPOSITORY/mypkg/current $PKGTMP/mypkg |
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.
Copy any template files associated with the distributed packages into the temporary directory, preserving the relative path to the template. For example:
$ mkdir -p $PKGTMP/templates
$ cp -p -R $ECOS_REPOSITORY/templates/mytemplate $PKGTMP/templates |
Remove any files from the temporary directory hierarchy which you do not want to distribute with the packages (eg object files, CVS directories).
Add a .bin 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:
$ find $PKGTMP -type f -name '*.gif' -exec mv {} {}.bin ';' |
The .bin suffix is removed during file extraction and is used to inhibit the manipulation of line endings by the eCos Package Administration Tool.
Extract the package records for the new packages from the package database file at $ECOS_REPOSITORY/ecos.db and create a new file containing these records at $PKGTMP/pkgadd.db (in the root of the temporary directory hierarchy). Any target records which reference the distributed packages must also be provided in pkgadd.db.
Rename the version directories under $PKGTMP (typically current 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 v1_0:
$ cd $PKGTMP/mypkg
$ mv current v1_0 |
the Section called Package Versioning describes the version naming conventions.
Rename any template files under $PKGTMP (typically current.ect during development) to reflect the version of the template you are distributing. For example, version 1.0 of a template may use the filename v1_0.ect:
$ cd $PKGTMP/templates/mytemplate
$ mv current.ect v1_0.ect |
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.
Optionally create a licence agreement file at $PKGTMP/pkgadd.txt containing the licensing terms under which you are distributing the new packages. Limit each line in this file to a maximum of 79 characters.
Create a GNU tar archive of the temporary directory hierarchy. By convention, this archive would have a name of the form <package_name>-<version>:
$ cd $PKGTMP
$ tar cf mypkg-1.0.tar * |
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.
Compress the archive using gzip and give the resulting file a .epk file extension:
$ gzip mypkg-1.0.tar
$ mv mypkg-1.0.tar.gz mypkg-1.0.epk |
The resulting eCos package distribution file (*.epk) is in a compressed format and may be distributed without further compression.