Renaming, Merging and Splitting Packages

The desired organization of a software component can change because of mistakes in the original packages, changes in the product or its usage over time, or changes in the surrounding software environment. Sometimes just the name of a package needs to change. When planning such changes, consider the user who is performing an upgrade, to ensure that unintended side effects do not occur.

Three types of package reorganization are discussed in this section, in order of increasingly complex considerations for pkg update:

1. Renaming single packages

2. Merging two packages

3. Splitting a package

Renaming a Single Package

Renaming a single package is straightforward. IPS provides a mechanism to indicate that a package has been renamed.

To rename a package, publish a new version of the existing package with the following two actions:

• A set action in the following form:

  set name=pkg.renamed value=true

• A require dependency on the new package.

A renamed package cannot deliver content other than depend or set actions.

The new package must ensure that it cannot be installed at the same time as the original package before the rename. If both packages are covered by the same incorporation dependency, this restriction is automatic. If not, the new package must contain an optional dependency on the old package at the renamed version. This ensures that the solver will not select both packages, which would fail conflict checking.

A user who installs this renamed package automatically receives the new named package, since it is a dependency of the old version. If a renamed package is not depended upon by any other packages, it is automatically removed from the system. The presence of older software can cause a number of renamed packages to be shown as installed. When that older software is removed, the renamed packages are automatically removed as well.

Packages can be renamed multiple times without issue, though this is not recommended since it can be confusing to users.

Merging Two Packages

Merging packages is straightforward as well. The following two cases are examples of merging packages:

• One package absorbs another package at the renamed version.

• Two packages are renamed to the same new package name.

One Package Absorbs Another

Suppose package A@2 must absorb package B@3. To do this, rename package B to package A@2. Remember to include an optional dependency in A@2 on B@3, unless both packages are incorporated so that they update together as described above. A user upgrading B to B@3 now gets A installed since A has absorbed B.

Two Packages Are Renamed

In this case, rename both packages to the name of the new merged package, including two optional dependencies on the old packages in the new one if they are not otherwise constrained.

Splitting a Package

When you split a package, rename each resulting new package as described in Renaming a Single Package. If one of the resulting new packages is not renamed, the pre-split and post-split versions of that package are not compatible and might violate dependency logic when the end user tries to update the package.

Rename the original package, and include require dependencies on all new packages that resulted from the split. This ensures that any package that had a dependency on the original package will get all the new pieces.

Some components of the split package can be absorbed into existing packages as a merge. See One Package Absorbs Another.