pkgtools/pkg_chk/files/pkg_chk.8

   1 .\"     $NetBSD: pkg_chk.8,v 1.25 2007/08/27 15:28:54 abs Exp $
   2 .\"
   3 .\" Copyright (c) 2001 by David Brownlee (abs@NetBSD.org)
   4 .\" Absolutely no warranty.
   5 .\"
   6 .Dd May 2, 2008
   7 .Dt PKG_CHK 8
   8 .Sh NAME
   9 .Nm pkg_chk
  10 .Nd check, and optionally update, installed packages
  11 .Sh SYNOPSIS
  12 .Nm
  13 .Op Fl aBbcfhiklNnpqrsuv
  14 .Op Fl C Ar conf
  15 .Op Fl D Ar tags
  16 .Op Fl L Ar file
  17 .Op Fl P Ar path
  18 .Op Fl U Ar tags
  19 .Sh DESCRIPTION
  20 .Nm
  21 verifies that the versions of installed packages matches those in
  22 pkgsrc, optionally adding missing or updating mismatched packages.
  23 .Pp
  24 It can verify all installed packages, or check against a set of packages
  25 based on the hostname, architecture, and other characteristics.
  26 .Pp
  27 When updating packages that depend on each other
  28 .Nm
  29 will skip dependent packages to reduce unnecessary rebuilding.
  30 .Pp
  31 .Ss Options
  32 .Bl -tag -width xxxxxxxx
  33 .It Fl a
  34 Automatically add any missing packages.
  35 If a binary package exists in
  36 .Pa ${PACKAGES}
  37 it will be used in preference to building from source, unless the
  38 .Fl b
  39 or
  40 .Fl s
  41 options are given.
  42 .It Fl B
  43 Include the "Build version" (see option
  44 .Fl b
  45 .Xr pkg_info 1 )
  46 of packages when determining if a package is up to date.
  47 .It Fl b
  48 Use binary packages.
  49 If
  50 .Fl s
  51 is not set this allows
  52 .Nm
  53 to run without
  54 .Ev PKGSRCDIR .
  55 .It Fl C Ar conf
  56 Use the
  57 .Pa pkgchk.conf
  58 file
  59 .Sq Ar conf .
  60 .It Fl D Ar tags
  61 Add the comma separated list of tags to those checked when parsing
  62 .Pa pkgchk.conf .
  63 Also includes
  64 .Ev PKGCHK_TAGS .
  65 .It Fl f
  66 Fetch all missing/mismatched packages found.
  67 Can be used with
  68 .Fl a
  69 or
  70 .Fl u
  71 to perform the fetch before any building.
  72 .It Fl g
  73 Generate an initial
  74 .Pa pkgchk.conf
  75 file based upon the packages installed on the host machine.
  76 .It Fl h
  77 Brief help.
  78 .It Fl k
  79 Continue with further packages if errors are encountered.
  80 .It Fl L Ar file
  81 Redirect the output for all commands run into the logfile
  82 .Pa file .
  83 Should be specified as a full pathname.
  84 On any error the tail end of the logfile will be displayed.
  85 .It Fl l
  86 List the filename for all binary packages (including best dependencies) based
  87 on
  88 .Pa pkgchk.conf .
  89 Will abort if a binary package is missing.
  90 This can be used (in conjunction with
  91 .Fl U
  92 and
  93 .Fl D )
  94 to determine what
  95 packages would need to be copied to a remote machine to ensure it
  96 was completely up to date.
  97 The list is sorted so that dependencies
  98 always come before packages which depend upon them.
  99 .It Fl N
 100 For each installed package, look if there is a newer version
 101 noted in
 102 .Pa ${PKGSRCDIR}/doc/TODO .
 103 Good for finding packages to update.
 104 .It Fl n
 105 Display actions that would be taken, but do not change anything.
 106 .It Fl P Ar path
 107 Set the path to the binary packages.
 108 Defaults to
 109 .Ev PACKAGES
 110 if
 111 .Ev PKGSRCDIR
 112 is available, or
 113 .Dq Pa \&.
 114 otherwise.
 115 .It Fl p
 116 Print list of package directories that will be checked, then exit.
 117 .It Fl q
 118 Do not display actions or take any action; only list information
 119 about package version differences.
 120 Useful for options that list information about package differences, such as
 121 .Fl a
 122 or
 123 .Fl u .
 124 .It Fl r
 125 Recursively delete any mismatched packages found.
 126 Use with care, this does not record which packages were installed
 127 for later update.
 128 .It Fl s
 129 Building missing packages from source.
 130 If UPDATE_TARGET=package is set in
 131 .Pa /etc/mk.conf ,
 132 then
 133 .Nm
 134 will automatically generate binary packages for later reuse.
 135 .It Fl U Ar tags
 136 Remove the comma separated list of tags from those checked when
 137 parsing
 138 .Pa pkgchk.conf .
 139 Also includes
 140 .Ev PKGCHK_NOTAGS .
 141 Package directories can also be skipped by listing them under
 142 .Fl U .
 143 Passing
 144 .Sq *
 145 to
 146 .Fl U
 147 will result in all default tags being unset
 148 .It Fl u
 149 Automatically update any missing packages.
 150 If a binary package exists in
 151 .Ev PACKAGES
 152 it will be used in preference to building from source, unless the
 153 .Fl b
 154 or
 155 .Fl s
 156 options are given.
 157 .Pp
 158 Note: If the update fails (particularly when building from source), the system
 159 will be left with missing packages.
 160 Once the error has been fixed, a second run will resume the update.
 161 .It Fl v
 162 Verbose - list the tags set when checking
 163 .Pa pkgchk.conf ,
 164 and all packages checked.
 165 .El
 166 .Ss Deprecated Options
 167 .Bl -tag -width xxxxxxxx
 168 .It Fl c
 169 Check versions of packages specified in
 170 .Pa pkgchk.conf .
 171 This is a synomyn for
 172 .Nm
 173 .Fl a q ,
 174 and will be removed in a future version.
 175 .It Fl i
 176 Check versions of installed packages, ignoring
 177 .Pa pkgchk.conf.
 178 This is a synomyn for
 179 .Fl u q ,
 180 and will be removed in a future version.
 181 .El
 182 .Sh FILE FORMAT
 183 Anything after a
 184 .Sq #
 185 on a line is considered a comment.
 186 .Pp
 187 Each line in
 188 .Pa pkgchk.conf
 189 can either define a new tag or a package directory
 190 (such as sysutils/skill), in each case followed by a list of tags.
 191 .Ss New tag groups
 192 Lines that define a new tag can be used to group tags to avoid
 193 repeating the same set of tags for multiple packages.
 194 For example:
 195 .Dl mailserver      \= tll gta tycoon jeeves iris
 196 would cause the mailserver tag to be set for any of the listed hosts.
 197 Note that the tags after the
 198 .Sq =
 199 are parsed with the same set of tag
 200 evaluation rules as those after package definitions (see later).
 201 .Ss Package definition lines
 202 Package directory lines are used to determine which packages are to be
 203 installed, checking the tags against the current defined set.
 204 .Ss Tag evaluation
 205 Tags on package directory are checked against the current machine's set:
 206 .Bl -bullet
 207 .It
 208 If a matched tag starts with a hyphen
 209 .Sq - ,
 210 the package is always excluded.
 211 .It
 212 Otherwise if any tags match the package will be included.
 213 .It
 214 A line without any tags matches all machines.
 215 .It
 216 An asterisk
 217 .Sq *
 218 matches any tag.
 219 .It
 220 If a tag starts with an
 221 .Sq /
 222 then it is checked for as a readable filename.
 223 .It
 224 Tags cannot contain a hyphen
 225 .Sq -
 226 or plus
 227 .Sq + .
 228 .It
 229 Tags separated by spaces are treated as
 230 .Dq or .
 231 .Dq taga tagb
 232 means if
 233 .Em taga
 234 or
 235 .Em tagb
 236 match the current machine.
 237 .It
 238 Tags separated by a plus are treated as
 239 .Dq and .
 240 .Dq taga+tagb
 241 means if
 242 .Em taga
 243 and
 244 .Em tagb
 245 match the current machine.
 246 .El
 247 .Pp
 248 The default set of tags used to determine which packages to match
 249 in
 250 .Pa pkgchk.conf
 251 are equivalent to the output of the following with
 252 any spaces converted to hyphens (-): hostname -s, hostname, uname
 253 -srm, uname -sr, uname -sm, uname -s, uname -r, uname -m.
 254 If
 255 .Pa /usr/X11R6/lib/libX11.so
 256 or
 257 .Pa /usr/X11R6/lib/libX11.a
 258 is present,
 259 .Em x11
 260 is added to the list of tags.
 261 Tags should not contain the - or + characters.
 262 To see tags for the current machine, run
 263 .Nm
 264 with the
 265 .Fl v
 266 option.
 267 .Sh ENVIRONMENT
 268 .Nm
 269 uses the following environment variables.
 270 .Bl -tag -width xxxx
 271 .It Ev MAKECONF
 272 Path to
 273 .Pa mk.conf .
 274 Defaults to
 275 .Pa @MAKECONF@ , @PREFIX@/etc/mk.conf ,
 276 or
 277 .Pa /etc/mk.conf .
 278 .It Ev PKGSRCDIR
 279 Base of pkgsrc tree.
 280 If not set in the environment, then this variable is read from
 281 .Pa ${MAKECONF} .
 282 If it is still not set, and if the current working directory
 283 appears to be inside a pkgsrc tree, then this variable
 284 is set to the base of that pkgsrc tree.
 285 Finally, if
 286 .Pa /usr/pkgsrc
 287 appears to contain a pkgsrc tree, then that is used as a last resort.
 288 .It Ev PKG_DBDIR
 289 pkgsrc database directory.
 290 If not set in environment then read from
 291 .Pa ${MAKECONF} .
 292 Defaults to
 293 .Pa /var/db/pkg
 294 .It Ev PACKAGES
 295 Location of binary packages.
 296 If not set in environment then read from
 297 .Pa /etc/mk.conf .
 298 Defaults to
 299 .Pa ${PKGSRCDIR}/packages .
 300 .Pp
 301 Unless in a completely homogeneous environment (every machine running
 302 exactly the same OS version and architecture) setting
 303 .Ev ${PACKAGES}
 304 in
 305 .Pa /etc/mk.conf
 306 to a value such as
 307 .Bd -literal
 308 ${PKGSRCDIR}/packages/${LOWER_OPSYS}-${OS_VERSION}-${MACHINE_ARCH}
 309 .Ed
 310 .Pp
 311 is strongly recommended.
 312 If
 313 .Em cpuflags
 314 (devel/cpuflags) is being used to optimally target individual CPU types,
 315 then
 316 .Ev ${CPU_DIR}
 317 should be appended to
 318 .Ev ${PACKAGES} .
 319 .It Ev PKGCHK_CONF
 320 Pathname to pkg_chk configuration file.
 321 If not set in environment then read from
 322 .Pa /etc/mk.conf .
 323 Defaults to
 324 .Pa ${PKGSRCDIR}/pkgchk.conf .
 325 .It Ev PKGCHK_UPDATE_CONF
 326 Pathname to temporary list of installed packages used when updating.
 327 If not set in environment then read from
 328 .Pa /etc/mk.conf .
 329 Defaults to
 330 .Pa ${PKGSRCDIR}/pkgchk_update-$(hostname).conf .
 331 Note, if pkgsrc is being
 332 shared across multiple machines which may be updating at the same time then
 333 it is important this file does not overlap between machines.
 334 .It Ev PKGCHK_TAGS
 335 Additional tags to add when parsing
 336 .Pa pkgchk.conf .
 337 .It Ev PKGCHK_NOTAGS
 338 Additional tags to unset when parsing
 339 .Pa pkgchk.conf .
 340 .El
 341 .Sh EXAMPLES
 342 Sample
 343 .Pa pkgchk.conf
 344 file:
 345 .Bd -literal
 346
 347 mailserver      = tll gta tycoon jeeves iris
 348
 349 # Install before others
 350 devel/cpuflags
 351 pkgtools/pkg_chk
 352
 353 # Mail related
 354 mail/exim                       *
 355 mail/spamassassin               mailserver
 356 mail/cyrus-imapd                mailserver
 357 mail/procmail                   mailserver bobhost
 358
 359 shells/standalone-tcsh          *
 360 wm/pwm                          /etc/X11/XF86Config
 361 misc/setiathome                 i386
 362 print/acroread                  /etc/X11/XF86Config+i386
 363 www/communicator                x11+sparc x11+sparc64
 364 www/navigator                   x11+i386
 365 x11/xlockmore                   x11 -wopr
 366
 367 .Ed
 368 .Sh AUTHORS
 369 .An David Brownlee
 370 .Aq abs@NetBSD.org ,
 371 plus much from Stoned Elipot.
 372 .Sh BUGS
 373 When used against binary packages,
 374 .Nm
 375 does not handle the directory containing multiple versions of the same package.