|
pkgmanager − a package management tool for pkgsrc |
|
pkgmanager command [options or arguments] |
|
If you read nothing else, read this: If you do not correctly configure your ´want list’, you will end up uninstalling most packages on your system, which is almost certainly not what you want. If you intend to use pkgmanager for the first time, it is strongly recommented that you read this man page from beginning to end. If you do not, then at least read the ’WANT LIST MANAGEMENT’ section. |
|
pkgmanager is a package manager for the pkgsrc packaging system. The primary goal of this software is to offer a simple and non-intrusive method by which to upgrade a pkgsrc installation. pkgmanager functionality is cenetered around the concept of a ’want list’, which is a list of packages the system administator wants to be installed on the system. This list must only contain those packages explicitly wanted; dependencies will be met automatically. Before pkgmanager is used for the first time, the want list must be manually populated (see ’WANT LIST MANAGEMENT’ for details). The want list is used to build a tree of packages required to be installed on the system. When the ’sync’ command is used, pkgmanager uses this list to bring the system up to date with respect to the software currently contained in the pkgsrc tree. This is done by a carefully selected sequence of package removals, package installs and package replacements. Under typical circumstances, most of the software on the system will remain operational during an upgrade (but this is not guaranteed). pkgmanager’s ’sync’ command difference from the use of ’make update’ or pkg_chk by the manner in which packages are upgraded. Instead of removing all packages slated for rebuild at the beginning, pkgmanager replaces one package at a time. |
|
The ’sync’ command instructs pkgmanager to synchronize the state of the package system with that of the pkgsrc tree. It does so by performing various operations in a very specific order which is determined by the want list and the package dependency hierarchy as it appears in the pkgsrc tree. For the purpose of the explanation of this procedure, the following package states are introduced: |
|
WANTED |
The package has been explicitly tagged as wanted by the administrator. |
|
ORPHANED |
|
The package is installed, but its original location in the pkgsrc tree no longer exists. This situation typically arrised because a package has been renamed, moved or removed. |
|
The package is installed and is directly or indirectly needed in order to satisfy the dependencies of one or more WANTED packages. |
|
UNNEEDED |
|
The package is installed, but not NEEDED. This typically happens when a package has been removed from the want list, a package was previously needed as a dependency but is no longer, or it is a result of a manual package installation performed by the administator without updating the pkgmanager want list. |
|
MISSING |
|
The package is directly or indirectly needed in order to satisfy the dependencies of one or more WANTED packages, but it is not currently installed. |
|
UPDATED |
|
The package is needed and installed, but the version in the pkgsrc tree is newer than that which is installed. |
|
DEPUPDATED |
|
The package has direct or indirect dependencies that are themselves UPDATED. |
|
DIRTY |
The package installation is older than one of its dependencies. This only refers to the time of the installation of the package, and is independent of whether the version in pkgsrc matches the version that is installed. |
|
In addition, the following states exist but are specific to a certain run of pkgmanager and is not reflected in any on-disk structure: |
|
FAILED |
The package has failed to install or upgrade. |
|
DEPFAILED |
|
The package has a direct or indirect dependencies that are FAILED. |
|
The synchronization procedure proceeds as follows: |
|
1. |
Any UNNEEDED or ORPHANED packages are deinstalled using pkg_delete -f. |
||
|
2. |
pkgmanager identifies all packages that are (1) MISSING or UPDATED or DIRTY and (2) not FAILED and (3) none of whose dependencies are MISSING, UPDATED, DIRTY or FAILED. The resulting list of packages is sorted by priority (see WANT LIST MANAGEMENT for more information on priorities). The first package in the resulting sorted list is selected for the next step. If the list is empty, the synchronization procedure is complete and pkgmanager terminates. |
||
|
3. |
If the selected package is MISSING, an attempt is made to install it. If the selected package is UPDATED or DIRTY, an attempt is made to update it using ’make replace’. |
||
|
4. |
If the installation or upgrade was successful, go to step 2. If the installation or upgrade failed, the package is marked as FAILED for the duration of this session. Go to step 2. |
|
The reason why UNNEEDED packages and ORPHANS are removed first is that pkgmanager is trying to avoid conflicts in the case of renamed packages. In addition, it is possible for a package to depend on one of multiple conflicting packages. If a changed package options causes a switch of such a dependency, a conflict would be created if pkgmanager attemted to install the new dependency before the old one is removed. |
|
The ’want list’ is a list of packages (with relative priority) that the administrator wants installed on the system. This list must only contain the packages specifically sought after; not their dependencies. pkgmanager is responsible for maintaining the set of installed packages such that the requirements of the want list are fulfilled. If a package that is on the want list is renamed, moved or deleted in pkgsrc, the want list must be manually updated to reflect reality. The priority of a package on the want list determines in which order packages are updated or installed. The higher the priority, the quicker it will be synchronzied (see ’SYNCHRONIZATION PROCEDURE’). The default priority for an item on the want list, if not specified, is 1.0. A few packages have a built-in standard priority unless overridden by the user: |
|
pkgtools/pkg_install |
|
has priority 1000.0 |
|
pkgtools/pkg_tarup |
|
has priority 900.0 |
|
pkgtools/digest |
|
has priority 900.0 |
|
wip/pkgmanager |
|
has priority 500.0 |
|
It is recommended that priorities used for day-to-day operations be kept below 500.0 in order to not cause problems (for example, installation/upgrades may fail because of an outdated pkg_install even though pkg_install is not a dependency of the package; therefore one wants pkgmanager to upgrade the "core" tools before anything else). The want list is modified by using the ’want’ and ’unwant’ commands to pkgmanager. Their parameters are a list of package designators. |
|
A package designator is used to designate a package in the pkgsrc tree, and optionally an associated priority. It has the format: |
|
<path>[,<priority>] |
|
For example: |
|
shells/zsh |
|
sync [-f] |
|
Inspects the system as required and prints a summary of actions that will be performed by the synchronization procedure. If the user chooses to continue at the prompt, the synchronization procedure, the details of which is documented in ’SYNCHRONIZATION PROCEDURE’, is initiated. If -f is given, pkgmanager will go ahead with the synchronization procedure without prompting. |
|
install <package [package [...]]> |
|
Equivalent of want <...> followed by a sync. |
|
uninstall <packages> |
|
Equivalent of unwant <...> followed by a sync. |
|
show-wants |
|
Display the list of wanted packages and their associated priorities alphabetical order. |
|
want <package [package [...]]> |
|
Add one or more packages to the wantlist. See ’PACKAGE DESIGNATORS’ for information on the format of the argument(s). |
|
unwant <package [package [...]]> |
|
Removes the specified packages from the want list. See ’PACKAGE DESIGNATORS’ for information on the format of the argument(s). |
|
flush−cache |
|
Flushes the summary cache. This is recommended after updating the pkgsrc tree. pkgmanager tries to detect the need to re-examine a package’s summary data, but detection may not always be adequate. |
|
fetch−updated |
|
Invoke ’make fetch’ on all packages that are UPDATED. |
|
fetch−pending |
|
Invoke ’make fetch’ on all packages that are pending for rebuild for any reason. Typically useful before a ’sync’, to ensure package files can at least be downloaded before attempting a large upgrade. |
|
fetch−needed |
|
Invoke ’make fetch’ on all NEEDED packages, regardless of whether a subsequent ’sync’ will try to build them. |
|
help |
Displays a short summary of command line options. |
|
Following is an example pkgmanager session on a system where pkgmanager has not been used before. |
|
pkgmanager want shells/zsh,2.0 editors/emacs,2.0 |
|
In this case, the user has given the favorite shell and editor maximum priority, followed by basic desktop utilities (the ion window manager). After that comes the more important daily tools, such as a movie player and a web browser. After this, at default priority 1.0, comes most other things with no particular importance. The very last want item is KDE because it takes a very long time to build, and the user does not want it to block the upgrade of other packages (see ´WANT LIST MANAGEMENT’ for information on why this matters). |
|
There are some significant known shortcomings in pkgmanager that may or may not be a problem, depending on usage: pkgmanager does not correctly handle packages that depend on one of multiple possible dependencies. For example, given |
|
DEPENDS+= snort{,−mysql,−pgsql}−[0−9]*:../../net/snort |
|
pkgmanager will always treat the dependency as net/snort, regardless of whether snort-mysql or snort-pgsql is installed. This happens because pkgmanager always wants to build a dependency tree that is entirely independent of what is currently installed on the system (in order to be deterministic for a given tree). Note that if another package depends on net/snort-mysql, pkgmanager will unknowingly try to install conflicting packages. pkgmanager provides no guarantee that installed packages remain working during an upgrade. While on average, most packages are likely to work throughout most of an upgrade procedure, since many updates to libraries are small, there is absolutely no mechanism in place to guarantee that this is the case. A future version of pkgmanager will support performing an upgrade in a chroot, and then upgrading the host system quickly using binary packages. If a package fails to upgrade, the part of the dependency tree that depends on that package will simply not be upgraded. No other intelligent action is performed. Thus, if an important library fails to build, you will end up with a half-updated system until that library is made to build correctly - after which pkgmanager can continue building packages that depend on it. pkgmanager currently requires that the pkgsrc pkg_* tools be in the PATH. pkgmanager builds its dependency graph using make print-summary-data. Apart from being slow, it does not appear to give a 100% correct view of dependencies. Some packages have been identified that are installed by other packages (or by the pkgsrc framework) without being dependencies. This seems to apply to packages that are handled specially within the pkgsrc framework. So far no reports have been received about this causing problems; all known packages that exhibit this behavior are quite small and quick to build, and seem not to be required during runtime. pkgmanager has no support for pkgviews. pkgmanager has been tested on NetBSD, FreeBSD and (a while ago) on DragonFly BSD. In general it should work, or require little modification to be made to work, on any platform where lang/clisp builds successfully. |
|
pkgmanager was written by |
|
Peter Schuller <peter.schuller@infidyne.com> |
|
This manpage was written by |
|
Peter Schuller <peter.schuller@infidyne.com> |
|
pkg_chk(8) |