PKGCHKXX(8)

NAME
pkgchkxx - check, and optionally update, installed packages

SYNOPSIS
pkgchkxx [-aBbcdfhiklNnpqrsuv] [-C conf] [-D tags] [-j concurrency] [-L file] [-P path] [-U tags]

DESCRIPTION
pkgchkxx verifies that the versions of installed packages matches those in pkgsrc, optionally adding missing or updating mismatched packages.

It can verify all installed packages, or check against a set of packages based on the hostname, architecture, and other characteristics.

When updating packages that depend on each other pkgchkxx will skip dependent packages to reduce unnecessary rebuilding.

  Options

-a  Automatically add any missing packages. If a binary package exists in ${PACKAGES} it will be used in preference to building from source, unless the -b or -s options are given.

-B  Include the "Build version" (see option -b pkg_info(1)) of packages when determining if a package is up to date.

-b  Use binary packages. If -s is not set this allows pkgchkxx to run without PKGSRCDIR.

-C conf
    Use the pkgchk.conf file ‘conf’.

-D tags
    Add the comma separated list of tags to those checked when parsing pkgchk.conf. Also includes PKGCHK_TAGS.

-d  do not clean the build directories after updating packages from source.

-f  Fetch all missing/mismatched packages found. Can be used with -a or -u to perform the fetch before any building.

-g  Generate an initial pkgchk.conf file based upon the packages installed on the host machine.

-h  Brief help.

-j concurrency
    Spawn up to the given number of threads for various bookkeeping tasks, defaults to the number of available CPUs. This option does not affect the number of make(1) jobs.

-k  Continue with further packages if errors are encountered.

-L file
    Copy the output for all commands run into the logfile file. Should be specified as a full pathname.

-l  List the filename for all binary packages (including best dependencies) based on pkgchk.conf. Will abort if a binary package is missing. This can be used (in conjunction with -U and -D) to determine what packages would need to be copied to a remote machine to ensure it was completely up to date. The list is sorted so that dependencies always come before packages which depend upon them.

-N  For each installed package, look if there is a newer version noted in ${PKGSRCDIR}/doc/TODO. Good for finding packages to update.

-n  Display actions that would be taken, but do not change anything.

-P path
    Set the path to the binary packages. Defaults to PACKAGES if PKGSRCDIR is available, or “~”. otherwise.

-p  Print list of package directories that will be checked, then exit.

-q  Do not display actions or take any action; only list information about package version differences. Useful for options that list information about package differences, such as -a or -u.

-r  Recursively delete any mismatched packages found. Use with care, this does not record which packages were installed for later update.

-s  Building missing packages from source. If UPDATE_TARGET=package is set in mk.conf, then pkgchkxx will automatically generate binary packages for later reuse.

-U tags
    Remove the comma separated list of tags from those checked when parsing pkgchk.conf. Also includes PKGCHK_NOTAGS. Package directories can also be skipped by listing them under -U. Passing ‘*’ to -U will result in all default tags being unset

-u  Automatically update any installed but out of date packages. If a binary package exists in PACKAGES it will be used in preference to building from source, unless the -b or -s options are given.

    Note: If the update fails (particularly when building from source), the system will be left with missing packages. Once the error has been fixed, a second run will resume the update.

-v  Verbose - list the tags set when checking pkgchk.conf, and all packages checked.

  Deprecated Options

-c  Check versions of packages specified in pkgchk.conf. This is a synonym for pkgchkxx -a -q, and will be removed in a future version.

-i  Check versions of installed packages, ignoring pkgchk.conf. This is a synonym for -u -q, and will be removed in a future version.

FILE FORMAT
Anything after a ‘#’ on a line is considered a comment.

Each line in pkgchk.conf can either define a new tag or a package directory (such as sysutils/skill), in each case followed by a list of tags.

  New tag groups
Lines that define a new tag can be used to group tags to avoid repeating the same set of tags for multiple packages. For example:
    mailserver = tll gta tycoon jeeves iris
would cause the mailserver tag to be set for any of the listed hosts. Note that the tags after the ‘=’ are parsed with the same set of tag evaluation rules as those after package definitions (see later).

  Package definition lines
Package directory lines are used to determine which packages are to be installed, checking the tags against the current defined set.

  Tag evaluation
Tags on package directory are checked against the current machine's set:

•   If a matched tag starts with a hyphen ‘-’, the package is always excluded.

•   Otherwise if any tags match the package will be included.

•   A line without any tags matches all machines.

•   An asterisk ‘*’ matches any tag.

•   If a tag starts with an ‘/’ then it is checked for as a readable filename.

•   Tags cannot contain a hyphen ‘-’ or plus ‘+’.

•   Tags separated by spaces are treated as “or”. “taga tagb” means if taga or tagb match the current machine.

•   Tags separated by a plus are treated as “and”. “taga+tagb” means if taga and tagb match the current machine.

The default set of tags used to determine which packages to match in pkgchk.conf are equivalent to the output of the following with any spaces converted to hyphens (-):

•   hostname -s

•   hostname

•   uname -srm

•   uname -sr

•   uname -sm

•   uname -s

•   uname -r

•   uname -m

If pkg-config(1) reports that the package “x11” exists, x11 is added to the list of tags.

Tags should not contain the - or + characters.

Setting the tag ‘*’ will cause all package lines to match, regardless of their tag values.

To see tags for the current machine, run pkgchkxx with the -v option.

ENVIRONMENT
pkgchkxx uses the following environment variables.

MAKECONF
    Path to mk.conf. Defaults to /usr/pkg/etc/mk.conf, /usr/pkg/etc/mk.conf, or /etc/mk.conf.

PKGSRCDIR
    Base of pkgsrc tree. If not set in the environment, then this variable is read from ${MAKECONF}. If it is still not set, and if the current working directory appears to be inside a pkgsrc tree, then this variable is set to the base of that pkgsrc tree. Finally, if /usr/pkgsrc appears to contain a pkgsrc tree, then that is used as a last resort.

PKG_DBDIR
    pkgsrc database directory. If not set in environment then read from ${MAKECONF}. Defaults to /usr/pkg/pkgdb.

PACKAGES
    Location of binary packages. If not set in environment then read from mk.conf. Defaults to ${PKGSRCDIR}/packages.

    Unless in a completely homogeneous environment (every machine running exactly the same OS version and architecture) setting ${PACKAGES} in mk.conf to a value such as

        ${PKGSRCDIR}/packages/${LOWER_OPSYS}-${OS_VERSION}-${MACHINE_ARCH}

    is strongly recommended. If cpuflags (devel/cpuflags) is being used to optimally target individual CPU types, then ${CPU_DIR} should be appended to ${PACKAGES}.

PKGCHK_CONF
    Pathname to pkgchkxx configuration file. If not set in environment then read from mk.conf. Defaults to ${PKGSRCDIR}/pkgchk.conf.

PKGCHK_UPDATE_CONF
    Pathname to temporary list of installed packages used when updating. If not set in environment then read from mk.conf. Defaults to ${PKGSRCDIR}/pkgchk_update-$(hostname).conf. Note, if pkgsrc is being shared across multiple machines which may be updating at the same time then it is important this file does not overlap between machines.

PKGCHK_TAGS
    Additional tags to add when parsing pkgchk.conf.

PKGCHK_NOTAGS
    Additional tags to unset when parsing pkgchk.conf.

EXAMPLES
Sample pkgchk.conf file:

    mailserver      = tll gta tycoon jeeves iris
    # Install before others
    devel/cpuflags
    pkgtools/pkg_chk
    # Mail related
    mail/exim                       *
    mail/spamassassin               mailserver
    mail/cyrus-imapd                mailserver
    mail/procmail                   mailserver bobhost
    shells/standalone-tcsh          *
    wm/pwm                          /etc/X11/XF86Config
    misc/setiathome                 i386
    print/acroread                  /etc/X11/XF86Config+i386
    www/communicator                x11+sparc x11+sparc64
    www/navigator                   x11+i386
    x11/xlockmore                   x11 -wopr

AUTHORS
-nosplit David Brownlee <abs@NetBSD.org>, plus much from Stoned Elipot. The option -j was added and the entire program was rewritten in C++ by PHO <pho@NetBSD.org> to gain speed.

BUGS
When used against binary packages, pkgchkxx -a does not always handle directories containing multiple package bases correctly, e.g. “py27-*” and “py310-*”, because pkgchkxx does not know which one should be installed.