> Producing and Maintaining Packages
Overview
Most pkg(5) packages directly contain the files (and other actions) that make up a software application. But there are also two kinds of packages that primarily contain other packages – or more correctly dependencies on other packages. These are metpackages and incorporations.
Metapackages and incorporations consist primarily (often solely) of dependencies on other packages. Otherwise they are constructed and used like any other package.
Make sure you read the Dependencies Best Practices document before reading this document.
Metapackages
A metapackage is a package that consists entirely of dependencies of the type require. Installing a metapackage installs all of the packages it depends on. Therefore a metpackage is a way to group a collection of packages into one package. It provides a convenient way for users to install a complete feature set (or product) using a familiar name rather than worrying about determining the set of related packages that make up the popular feature set.
For example in OpenSolaris there is a netbeans metapackage that contains dependencies on all of the commonly installed Netbeans packages. To install Netbeans you just install the netbeans metapackage.
For some projects defining a metapackage is not necessary. This may be the case when a project has a natural dependency hierarchy that results in metapackage like behavior. For example if there is an obvious top level package that defines all of its dependencies, and installing that top level pacakge results in all packages being installed, then defining a metapackage is likely unnecessary.
On the other hand some large projects may want to create more than one metapackage because the product can be split into a number of useful profiles. For example GlassFish could define a glassfish-web metapackage that installs the web profile of GlassFish and a glassfish-j2ee metapackage that installs the J2EE profile.
In some circles metapackages are also referred to as package clusters. In this document we will stick with term metapackage.
Incorporations
An incorporation is a package that consists entirely of dependencies of the type incorporate. Installing an incorporation ensures that packages already installed on the system are brought up to the release levels stated in the dependencies in the incorporation. Since incorporate dependencies are a type of optional dependency, installing an incorporation does not result in any new packages being installed on the system – just (possibly) new versions of existing packages. Also, having an incorporation installed on the system will constrain package versions to the release families used in the dependencies defined in the incorporation (see Dependencies Best Practices for more info on incorporate dependencies).
For example in OpenSolaris there is a netbeans-incorportion package that contains incorporate dependencies on all of the Netbeans packages (note that the netbeans metapackage contains netbeans-incorporation to make sure it gets installed). There is also an entire incorporation that contains all of the packages in the OpenSolaris base distribution. Any time the entire package is updated, it ensures that all dependencies contained in entire are updated to the release levels stated in the dependency definitions in entire. In this way incorporations ensure that the packages on the system are updated to a known set of versions.
Let's look a little closer at the entire package in OpenSolaris. When you first install OpenSolaris 2008.5 you will have the 0.86 revision of the entire incorporation installed on your system. This represents build 86 of OpenSolaris. If you look at entire (try: pkg contents -m entire) you will see it contains incorporate dependencies on the build 86 revisions of the base Solaris packages. Later, when you do a pkg image-update you will update your system to the latest version of the entire package – say revision 0.99 (build 99). This ensures that all installed Solaris packages are updated to the versions in build 99, but no newer! Say down the road the 0.100 revision of SUNWlibcsl is pushed to the repository, but the entire incorporation remains the same. If you do an image-update you will not get the 0.100 revision of SUNWlibcsl. Why? Because the 0.99 version of the entire incorporation is capping the version of SUNWlibcsl at revision 0.99. This is a key difference between incorporate dependencies and normal optional dependencies. If the incorporation contained an optional dependency on SUNWlibcsl, then it would have updated to revision 0.100 on the update, but instead the incorporate dependency capped it at 0.99.
Another way to think of an incorporation is that it freezes a collection of packages at a certain version level. The packages stay at that level until a new version of the incorporation (with updated dependencies) is released. This freeze also impacts installing a new package. I can't install a version of a package that is newer than the release family specified in the incorporation unless I remove or update the incorporation.
Best Practices
| # | Title | Description |
|---|---|---|
| 1 | Consider creating a metapackage when you have multiple packages. | If your project contains multiple packages consider providing a metapackage to make it convenient to install your project by installing one package. |
| 2 | Multiple metapackages may be appropriate for large projects. | Large projects may find it convenient to define multiple metapackages that create tailored subsets of their product. For example there may be an "entire" metapackage, a "minimized" metapackage, a "developer" metapackage, etc. |
| 3 | Name your metapackage with a simple, recognizeable name | An appropriate name may be your product or project name. For example "netbeans". |
| 4 | A metapackage need not re-state every package dependency. | It is acceptable to just include top level packages in a metapackage, and to rely on the top level packages to state dependencies on other packages that they require. |
| 5 | Follow the Dependencies Best Practices when specifying version constraints in incorporations and metapackages. | In general the version constraints for packages delivered by your project should be tight, while the constraints on packages delivered outside of your project should be loose, but see th best practice for more details. |
| 6 | Make sure the version constraints used in any metapackage or incorporation is consistent with the version constraints used in your package dependencies. | In general you want the same version constraints used in your metapackage and incorporation as you use in your direct dependencies between packages. |
| 7 | Include a useful description for metapackages and incorporations. | For example something like: "This package is a metapackage for the GlassFishv3 J2EE container. Installing this package will install everything you need to use J2EE..." |
| 8 | Name your incorporations with a simple, recognizeable name ending with "-incorporation" | An appropriate name may be your product or project name followed by "-incorporation". For example netbeans-incorporation. Note that we aren't necessarily thrilled with the name "incorporation", but have not come up with a better alternative. |
| 9 | Use incorporations to constrain updates along release families | If it is important for updates to your packages to be aligned along release families then create an incorporation which is updated every time you roll out an update to your project. |
| 10 | Ensure your incorporation is installed with your product. | If you have a metapackage then make sure your incorporation is included in the metapackage. Also if you have an installer make sure your incorporation is always installed by the installer. |
| 11 | Take care when including packages delivered outside of your project in an incorporation. | When you include a package from another project in your incorporation you will be constraining it for all packages that depend on it – even those from other projects. Be aware of this and the possible consequences that this may entail for your distribution. |
| 12 | Pre-install your incorporation | If you are shipping a pre-installed image then it is likely a good idea to pre-install your incorporation so that its constraints are used when installing/updating packages |
Sign up or Log in to add a comment or watch this page.