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:
Renaming single packages
Merging two packages
Splitting a 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 no content and 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.
depend fmri=pkg:/newpkgname@version type=require
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 incorporate 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 packages is straightforward as well. The following two cases are examples of merging packages:
One package absorbs another package at the renamed version.
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 to the same new package name.
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.
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 How to Enable Your Application to Use a Shared Area.