path: root/pkgtools/pkg_chk/files/pkg_chk.8

.\"	$NetBSD: pkg_chk.8,v 1.6 2005/01/29 15:36:30 abs Exp $
.\"
.\" Copyright (c) 2001 by David Brownlee (abs@NetBSD.org)
.\" Absolutely no warranty.
.\"
.Dd November 30, 2004
.Dt PKG_CHK 1
.Sh NAME
.Nm pkg_chk
.Nd check, and optionally update, installed packages
.Sh SYNOPSIS
.Nm
.Op Fl aBbcfhiklnrsuv
.Op Fl C Ar conf
.Op Fl D Ar tags
.Op Fl L Ar file
.Op Fl P Ar file
.Op Fl U Ar tags
.Sh DESCRIPTION
.Nm
verifies that the versions of installed packages matches those in
pkgsrc, optionally adding missing or updating mismatched packages.
.Pp
It can verify all installed packages, or check against a set of packages
based on the hostname, architecture, and other characteristics.
.Pp
When updating packages that depend on each other
.Nm
will skip dependent packages to reduce unnecessary rebuilding.
.Pp
.Sy Options
.Bl -tag -width xxxxxxxx
.It Fl a
Automatically add any missing packages.
If a binary package exists in
.Ev ${PACKAGES}
it will be used in preference to building from source, unless the
.Fl b
or
.Fl s
options are given.
.It Fl B
Check the "Build version" (see option -b of pkg_info(1)) of packages.
.It Fl b
Use binary packages. If
.Fl s
is not set this allows
.Nm
to run without PKGSRCDIR.
.It Fl C Ar conf
Use the
.Pa pkgchk.conf
file
.Sq Ar conf .
.It Fl c
Check versions of packages specified in
.Pa pkgchk.conf .
.It Fl D Ar tags
Add the comma separated list of tags to those checked when parsing
.Pa pkgchk.conf .
Also includes
.Ev PKGCHK_TAGS .
.It Fl f
Fetch all missing/mismatched packages found.
Can be used with
.Fl a
or
.Fl u
to perform the fetch before any building, or with
.Fl c
or
.Fl i
to just fetch missing/mismatches packages.
.It Fl g
Generate an initial
.Pa pkgchk.conf
file based upon the packages installed on the host machine.
.It Fl h
Brief help.
.It Fl i
Check versions of installed packages, ignoring
.Pa pkgchk.conf .
.It Fl k
Continue with further packages if errors are encountered.
.It Fl L Ar file
Redirect the output for all commands run into the logfile
.Pa file .
Should be specified as a full pathname.
On any error the tail end of the logfile will be displayed.
.It Fl l
List the filename for all binary packages (including the exact dependencies
against which each package was built) based on
.Pa 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.
.It Fl n
Display actions that would be taken, but do not change anything.
.It Fl r
Recursively delete any mismatched packages found.
Use with care, this does not record which packages were installed
for later update.
.It Fl s
Building missing packages from source.
If DEPENDS_TARGET=package is set in
.Pa /etc/mk.conf ,
then
.Nm
will automatically generate binary packages for later reuse.
.It Fl P Ar path
Set the path to the binary packages. Defaults to PACKAGES if PKGSRCDIR
is available, or '.' otherwise.
.It Fl U Ar tags
Remove the comma separated list of tags from those checked when
parsing
.Pa pkgchk.conf .
Also includes
.Ev PKGCHK_NOTAGS .
Package directories can also be skipped by listing them under
.Fl U
.It Fl u
Automatically update any missing packages.
If a binary package exists in PACKAGES it will be used in preference
to building from source, unless the
.Fl b
or
.Fl s
options are given.
.Pp
Note: If the update fails (particularly when building from source), the system
will be left with missing packages.
.It Fl v
Verbose - list the tags set when checking
.Pa pkgchk.conf ,
and all packages checked.
.El
.Sh FILE FORMAT
Each non comment line in
.Pa pkgchk.conf
should contain a package
directory (such as sysutils/skill) followed by an optional list of
tags.
Tags are checked against the current machine's set:
.Bl -bullet
.It
If a matched tag starts with a hyphen
.Sq - ,
the package is always excluded.
.It
Otherwise if any tags match the package will be included.
.It
A line without any tags matches all machines.
.It
An asterisk
.Em *
matches any tag.
.It
If a tag starts with an
.Em /
then it is checked for as a readable filename.
.It
Tags cannot contain a hypen
.Sq -
or plus
.Sq + .
.It
Tags separated by spaces are treated as
.Dq or .
.Dq taga tagb
means if
.Em taga
or
.Em tagb
match the current machine.
.It
Tags separated by a plus are treated as
.Dq and .
.Dq taga+tagb
means if
.Em taga
and
.Em tagb
match the current machine.
.El
.Pp
The default set of tags used to determine which packages to match
in
.Pa pkgchk.conf
are equivalent to the output of the following with
any spaces converted to hypens (-): hostname -s, hostname, uname
-srm, uname -sr, uname -sm, uname -s, uname -r, uname -m.
If
.Pa /usr/X11R6/lib/libX11.so
or
.Pa /usr/X11R6/lib/libX11.a
is present,
.Em x11
is added to the list of tags.
Tags should not contain the - or + characters.
To see tags for the current machine, run
.Nm
with the
.Fl v
option.
.Sh ENVIRONMENT
.Nm
uses the following environment variables.
.Bl -tag -width xxxx
.It Ev PKGSRCDIR
Base of pkgsrc tree.
If not set in environment then read from
.Pa ${MAKECONF}
or
.Pa /etc/mk.conf .
Defaults to
.Pa /usr/pkgsrc
.It Ev PKG_DBDIR
pkgsrc database directory.
If not set in environment then read from
.Pa ${MAKECONF}
or
.Pa /etc/mk.conf .
Defaults to
.Pa /var/db/pkg
.It Ev PACKAGES
Location of binary packages.
If not set in environment then read from
.Pa /etc/mk.conf .
Defaults to
.Pa ${PKGSRCDIR}/packages .
.Pp
Unless in a completely homogeneous environment (every machine running
exactly the same OS version and architecture) setting
.Ev ${PACKAGES}
in
.Pa /etc/mk.conf
to a value such as
.Bd -literal
${PKGSRCDIR}/packages/${LOWER_OPSYS}-${OS_VERSION}-${MACHINE_ARCH}
.Ed
.Pp
is strongly recommended.
If
.Em cpuflags
(devel/cpuflags) is being used to optimally target individual CPU types,
then
.Ev ${CPU_DIR}
should be appended to
.Ev ${PACKAGES} .
.It Ev PKGCHK_CONF
Pathname to pkg_chk configuration file.
If not set in environment then read from
.Pa /etc/mk.conf .
Defaults to
.Pa ${PKGSRCDIR}/pkgchk.conf .
.It Ev PKGCHK_TAGS
Additional tags to add when parsing
.Pa pkgchk.conf .
.It Ev PKGCHK_NOTAGS
Additional tags to unset when parsing
.Pa pkgchk.conf .
.El
.Sh EXAMPLES
Sample
.Pa pkgchk.conf
file:
.Bd -literal
# Must install before others
devel/cpuflags
pkgtools/xpkgwedge              x11

shells/standalone-tcsh          *
wm/pwm                          x11
misc/setiathome                 i386
print/acroread                  x11+i386
www/communicator                x11+sparc x11+sparc64
www/navigator                	x11+i386
x11/xlockmore                   x11 -wopr

.Ed
.Sh AUTHORS
.An David Brownlee
.Aq abs@netbsd.org ,
plus much from Stoned Elipot.
.Sh BUGS
Updating packages on which other packages depend can currently only be done
via source (not binary packages).
.Pp
If both package
.Em a
and package
.Em b
are to be updated, and
.Em a
depends on
.Em b ,
.Nm
will correctly skip the update of
.Em a .
However, if
.Em a
depends on
.Em b
and
.Em c ,
and all three are marked for update,
.Nm
will update
.Em b
and
.Em c
in two separate passes, resulting in unnecessary rebuilding of
.Em a
(and potentially other packages).
.Pp
There exists a workaround, if you have a complete
.Pa pkgchk.conf :
.Bd -literal
# pkg_chk -ra

.Ed
will remove all outdated packages and then install all
files that are in your
.Pa pkgchk.conf
file, but not currently installed, i.e. hopefully all
that you just deleted, if the file was complete.