pkg_install: The complete reference


Table of Contents

1. Packages names, versions and dependencies
The package name
Package versions
Package matching
2. Package meta data
Dependency, conflict and compatibility specifications
Dependencies
ABI compatibility
Package conflicts
File and directory list
Files
Directories
Hardlinks
Symlinks
Template-based files
Configuration directories
Volatile filess
Exclusive directories
Trigger

Chapter 1. Packages names, versions and dependencies

The package name

The naming of packages is mostly arbitrary and a choice of the original authors. pkgsrc applies a number of conventions however. The package name contains two parts, the base name (everything before the last hyphen) and the version string (everything after the last hyphen).

To distinguish categories of packages, a number of prefixes are used in the system:

  • Python modules are commonly prefixed with a version specific string like py24-. This allows the concurrent use of the same Python module built for multiple Python versions.

  • PHP packages are commonly prefixed with either php4- or php5-, depending on the version. PEAR packages get an additional pear- prefix, resulting e.g. in php5-pear- as prefix.

Package versions

The version string is the part of a package name after the last hyphen. It is split into (type, value) pairs according to the following rules:

  1. A run of digits is converted to a 32bit signed integer. Type is 0.

  2. If the string begins with ".", the pair (2, 0) is used.

  3. If the string begins with "alpha", "beta", "pre", "rc", "pl" or "_", the pair (-3, 0), (-2, 0), (-1,0), (-1,0), (2, 0) or (2, 0) respectively is used.

  4. If the string begins with "nb", the pair (1, 0) is returned. This substring must occur at most once in a version string. It can be followed by pairs from the first two rules only.

  5. An initial letter gets a type of 2 and as value the difference between the corresponding ASCII lower case letter and and 'a' therein.

Version strings are compared and ordered by converting them to lists of pairs as above and applying the order relation sequentally. Version strings of different length are always inequal. Ordering is following normal lexicographic rules.

Package matching

Package matching is performed in two situations:

  1. A package name can match a specific pattern to fulfill a dependency or be considered vulnerable.

  2. When installing dependencies of a package, multiple package names might match. In that case the pattern should provide means to select the best match.

Simple patterns consist of a package base name and optionally comparison terms. The package base name from the package and the pattern are compared and need to be equal for a match. Comparison terms consist of an operand (<, <=, ==, !=, >=, > or ~) and a version string (the operand). The pattern is matched if all comparison terms are fulfilled. The "~" operator is a prefix-match, e.g. a package version matches it if it begins with the same pairs as the operand. Two matching package names are ordered directly by comparing the version numbers.

Alternative patterns consists of one or more simple patterns separated by "|". The pattern is matched if any of the simple patterns is matched. Two matching package names are ordered by the order of the matching simple patterns. If both package names have the same first match, the order rules for simple packages apply.

Chapter 2. Package meta data

Dependency, conflict and compatibility specifications

Dependencies

Dependencies express the requirement of a package for functionality provided by a different package. pkgsrc distinguishes between three types of dependencies:

  • Build dependencies are needed for building the package from source, they are not needed afterwards. However, the packages used are recorded for reference purpose.

  • Runtime dependencies are needed by the installed package to provide e.g. an interpreter or a shared library.

  • Buildlink dependencies are needed for building other packages which depend on this one. They can be build or runtime dependencies and are added to the dependency list of the package being built.

Note

Buildlink dependencies are a future direction and the issues are not fully understood yet.

For each type a list of patterns is recorded.

When installing packages, each pattern in the runtime dependency list is first matched against the current set of packages. If it doesn't match an already installed package, the list of packages to installed is matched and the reordered when a match was found. If that doesn't fulfill the dependency either, the best match from all available uninstalled packages is used. An unresolvable pattern is a hard error and the depending package can not be installed. The system has to also ensure that the removal or an update of a package does not result in packages with unresolved dependencies.

ABI compatibility

For updating packages the system has to ensure that the new package can replace the old version without breaking the packages using it. This means that the file formats and especially the shared libraries of the new version must be compatible to the old version. For this, packages express explicitly to which versions they are ABI compatible.

A direct update is allowed only if the new version announces its compatiblity with the old version and fulfills all dependencies of the old version. The system should record all provided shared object names of ELF binaries in the package, or similiar information for other executable formats. This information can be used to assist maintainers during the process of updating the build description.

Package conflicts

Conflicts occur, when two packages can't be installed at the same time. The most basic conflict results from overlapping PLISTs. This conflicts can be detected automatically and handled as error during the installation process, but making them explicit allows the system to detect and possibly resolve them earlier. The second class of conflicts is the result of incompatible file formats in shared resources.

File and directory list

Files

Files have basic permissions (mode, owner, group) and associated content. The content is stored out-of-band, e.g. in the package tarball or the filesystem. For the content, checksums can be stored as well as the time of the last modification and the length of the it. Normal files can be children only of normal directories and must be relative to PREFIX. They are leafs of the directory tree.

Directories

Directories have only the basic permissions associated. They are created on-demand with default permissions and removed when the last entry and reference is gone. If a package should be created on-demand and it does already exist, it will be recorded in a special "system" package to prevent automatic removal.

Hardlinks

Hardlinks have a target path associated, which must be a file in the same package. If the creation of a hardlink failed, a symlink to the same file with default permissions will be created instead. Hardlinks can exist whereever normal files can occur.

Symlinks

Symlinks have the target path and the basic permissions associated. Symlinks inside PREFIX should be relative, but this is not enforced. Symlinks can occur as children of normal directories, but not configuration or exclusive directories.

Template-based files

Template-based files are used for configuration files et al. They have basic permissions and a template path associated. On installation, the template file is created by copying from the template path, if it does not exist. An empty template means that the file should be created as empty, if necessary. Template-based files can occur as children of normal or configuration directories.

Configuration directories

Configuration directories mark directories, where additional user managed files can exist. Package management tools should consider all entries as associated with the package and e.g. backup them on removal of the package. Configuration directories have the basic permissions associated.

Volatile filess

Volatile files work like template-based files, but are automatically removed on deinstallion.

Exclusive directories

Exclusive directories mark a directory for the direct control of a package. The content should be ignored by package management tools and no other package list entries are allowed in them. Each exclusive directory can only belong to one package. Exclusive directories have the basic permissions associated.

Trigger

XXX installation/removal trigger, font handling, virtual dependencies, ...