Chapter 27. Managing the Package Repository

A source distribution of eCos consists of a number of packages, such as the kernel, the C library, and the µITRON subsystems. These are individually versioned in the tree structure of the source code, to support distribution on a per-package basis and to support third party packages whose versioning systems might be different. A command-line tool, ecosadmin.tcl is used is used to manage the installation and removal of packages from a variety of sources with potentially multiple versions. A graphical user interface is also provided to this tool through a dialog box from the eCos Configuration Tool as illustrated Figure 27.1, “ Package Administration.

The presence of the version information in the source tree structure might be a hindrance to the use of a separate source control system such as CVS or SourceSafe. To work in this way, you can rename all the version components to some common name (such as “current”) thus unifying the structure of source trees from distinct eCos releases.

The eCos build system will treat any such name as just another version of the package(s), and support building in exactly the same way. However, performing this rename invalidates any existing build trees that referred to the versioned source tree, so do the rename first, before any other work, and do a complete rebuild afterwards. If you do have an existing configuration you wish to move over to a new structure, you are advised to use the process described in Section 15.2, “Switching Targets, Repositories and Versions”.

27.1. Package Installation

Package installation and removal is performed using the eCos command line tool ecosadmin.tcl, also known as the eCos Package Administration Tool, or through the eCos Configuration Tool. The latter provides a GUI interface to the former. This tool is a Tcl script which allows the user to add new eCos packages and new versions of existing packages to an eCos repository. Such packages must be distributed as a single file in the eCos package distribution format. By convention, eCos package distribution files are given the .epk suffix. Unwanted packages may also be removed from the repository using this tool.

27.1.1. Using the Package Administration Tool

The graphical interface accesses all the functionality of the command-line tool and may be accessed from the menu option ToolsAdministration. You will first be prompted to save your existing configuration before the dialog in Figure 27.1, “ Package Administration is displayed.

Figure 27.1.  Package Administration

Package Administration

The dialog displays the packages which are currently installed in the form of a tree. The installed versions of each package may be examined by expanding the tree.

Packages within a package distribution file (traditionally with a .epk suffix) may be added to the eCos repository, or if using multiple repositories the top-most repository, by clicking on the Add button. You will be prompted to provide the location and filename of the package distribution file via a File Open dialog box.

Packages may be removed by selecting a package in the tree and then clicking on the Remove button. If a package node is selected, all versions of the selected package will be removed. If a package version node is selected, only the selected version of the package will be removed.

27.1.2. Using the command line

The ecosadmin.tcl script is located in the base of the eCos repository. Use a command of the following form:

$ tclsh ecosadmin.tcl <command>

The following commands are available:

add <file>

Adds the packages contained with the specified package distribution file to the eCos repository and updates the package database accordingly.

remove <package> [ --version=<version> ]

Removes the specified package from the eCos repository and updates the package database accordingly. Where the optional version qualifier is used, only the specified version of the package is removed.

list

Produces a list of the packages which are currently installed and their versions. The available templates and hardware targets are also listed.

merge <package directory>

Merges all the packages within <package directory> into the current repository (defined by the environment variable ECOS_REPOSITORY).

Note that is is possible to remove critical packages such as the common HAL package using this tool. Users should take care to avoid such errors since core eCos packages may only be re-installed in the context of a complete re-installation of eCos.

27.2. Package Structure

The files in an installed eCos source tree are organized in a natural tree structure, grouping together files which work together into Packages. For example, the kernel files are all together in:

BASE_DIR/kernel/<version>/include/
BASE_DIR/kernel/<version>/src/
BASE_DIR/kernel/<version>/tests/

and µITRON compatibility layer files are in:

BASE_DIR/compat/uitron/<version>/include/
BASE_DIR/compat/uitron/<version>/src/
BASE_DIR/compat/uitron/<version>/tests/

The feature of these names which is of interest here is the <version> near the end. It may seem odd to place a version number deep in the path, rather than having something like BASE_DIR/<version>/...everything... or leaving it up to you to choose a different install-place when a new release of the system arrives.

The rationale for this organization is historic as in practice developers maintain their source code under revision control systems such as Mercurial, GIT or SourceSafe using the version directory current in place of <version> throughout. The version directory current is favored by most developers.

The <version> schema is still maintained as it does permit developers to easily switch between different versions of specific packages within their configuration without having to manipulate their revision control system or partion packages into their own revision control system. It also permits develops to upgrade only specific packages to newer versions while retaining the remainder on earlier versions that have been previously qualified by a standards or certification agency.

27.2.1. Integration with Revision Control Systems

Many developers have their own source code control system, version control system or equivalent, and will want to use it with eCos and eCosPro sources. Since new releases of eCos and eCosPro come with different pathnames for all the source files, a little work is necessary to import a new release into your source repository.

For example, eCosCentric maintains eCosPro within Mercurial, a distributed source revision control system, using a number of source repositories with all package versions as current . An eCosPro release is constructed by merging all repositories into a new single release directory and renaming all current directories to <version> , as well as setting the <version> of all templates.

An eCosPro release may therefore be returned into a source revision control system by renaming all <version> directories below packages back to current and committing the resulting directory structure into the repository.

“current” is recommended because ecosconfig recognizes it and places it first in any list of versions.

For example, within a POSIX shell environment such as bash (normally available under Linux and provided with the eCosPro host tools for Windows hosts) use the following command:

find . -name <version> -type d -printf 'mv %p %h/current\n' | bash

Having carried out such a renaming operation, your source tree will now look like this:

BASE_DIR/kernel/current/include/
BASE_DIR/kernel/current/src/
BASE_DIR/kernel/current/tests/
...
BASE_DIR/compat/uitron/current/include/
BASE_DIR/compat/uitron/current/src/
BASE_DIR/compat/uitron/current/tests/

which is a suitable format for import into your own source code control system. When you get a subsequent release of eCosPro, do the same thing and use your own source code control system to manage the new source base, by importing the new version from

NEW_BASE_DIR/kernel/current/include/

and so on.

The eCos build tool will now offer only the “current” version of each package; select this for the packages you wish to use.

Alternatively you may choose to create two versions of each package with each <version> directory lying alongside the next and current containing the most recent <version>. For example:

cd $ECOS_REPOSITORY
find . -name <version> -type d -printf 'cp -r %p %h/current\n' | bash

Having carried out such a copy operation, your source tree will now look like this:

BASE_DIR/kernel/current/include/
BASE_DIR/kernel/<version>/include/
BASE_DIR/kernel/current/src/
BASE_DIR/kernel/<version>/src/
BASE_DIR/kernel/current/tests/
BASE_DIR/kernel/<version>/tests/
...
BASE_DIR/compat/uitron/current/include/
BASE_DIR/compat/uitron/<version>/include/
BASE_DIR/compat/uitron/current/src/
BASE_DIR/compat/uitron/<version>/src/
BASE_DIR/compat/uitron/current/tests/
BASE_DIR/compat/uitron/<version>/tests/

In simple terms, while you initially may have two identical version directories, when you overlay a new version on top of an existing directory tree, the older files within current will be replaced by the newer <version> . Within your configuration, however, all packages marked to use the older version will remain fixed while those marked to use current will switch to a newer version.

The above simple method, however, is strongly discouraged. Care must be taken when merging two packages directories from different release repositories. For example, the file ecos.db is not versioned and is common to both releases' packages directories. Changes to made to this file will be lost. In addition, the target definition within ecos.db for a newer release may contain additional packages, such a new device driver which was not present in the older version of ecos.db. Developers are therefore advised to use the merge command of the ecosadmin.tcl tool which will merge the two versions of ecos.db in addition to overlaying new <version> subdirectories into the target repository. In addition, while merge will copy over the newer <version> subdirectories it will not replace the contents of pre-existing subdirectories such as current. This may, however, be made an option in a newer release of the ecosadmin.tcl tool and currently can be overcome through the following commands:

cd NEW_REPOSITORY
find . -name <version> -type d -printf 'cp -rf %p/. $ECOS_REPOSITORY/%h/current\n' | bash
[Note]Note

For the example given, the updated target definition in the merged repository will require use of the new device driver not present in the older release as a result of the updated target definition within ecos.db.

[Warning]Warning

Making such a change has implications for any build trees you already have in use. A configured build tree contains information about the selected packages and their selected versions. Changing the name of the “versioning” folder in the source tree invalidates this information, and in consequence it also invalidates any local configuration options you have set up in this build tree. So if you want to change the version information in the source tree, do it first, before investing any serious time in configuring and building your system. When you create a new build tree to deal with the new source layout, it will contain default settings for all the configuration options, just like the old build tree did before you configured it. You will need to redo that configuration work in the new tree.

Moving source code around also invalidates debugging information in any programs or libraries built from the old tree; these will need to be rebuilt.