usr.sbin/pkg_install/version/pkg_version.1

   1 .\"
   2 .\" Copyright 1998 Bruce A. Mah
   3 .\"
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\"     $FreeBSD: src/usr.sbin/pkg_install/version/pkg_version.1,v 1.5.2.14 2002/06/21 16:42:26 charnier Exp $
  27 .\"     $DragonFly: src/usr.sbin/pkg_install/version/Attic/pkg_version.1,v 1.2 2003/06/17 04:29:59 dillon Exp $
  28 .Dd July 17, 1998
  29 .Dt PKG_VERSION 1
  30 .Os
  31 .Sh NAME
  32 .Nm pkg_version
  33 .Nd summarize installed versions of packages
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl cdhv
  37 .Op Fl l Ar limchar
  38 .Op Fl L Ar limchar
  39 .Op Fl s Ar string
  40 .Op Ar index
  41 .Nm
  42 .Op Fl t Ar version1 version2
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 command is used to produce a report of non-base software packages
  47 installed using the
  48 .Xr pkg_add 1
  49 command.
  50 .Pp
  51 Each package's version number is checked against one of two sources to
  52 see if that package may require updating.  If the package contains
  53 information about its origin in the
  54 .Fx
  55 ports tree, and a version number can be determined from the port's
  56 .Pa Makefile ,
  57 then the version number from the
  58 .Pa Makefile
  59 will be used to determine whether the installed package is up-to-date
  60 or requires updating.
  61 .Pp
  62 If no origin for a package can be found, or if the port's
  63 .Pa Makefile
  64 cannot be located,
  65 .Nm
  66 will search for the package in the ports collection index file
  67 (typically
  68 .Pa /usr/ports/INDEX ) .
  69 Any matching version number(s) there will be used to determine whether
  70 the installed package is up-to-date or requires updating.
  71 .Pp
  72 Generally, using the version number from a port's
  73 .Pa Makefile
  74 will provide a more accurate result, since, unlike the index file, it
  75 provides an unambiguous current version number, even when multiple
  76 versions of a port exist in the ports collection.
  77 Moreover, the ports collection index file is only updated at
  78 intervals, meaning that it may not completely reflect the version
  79 numbers of the software contained in the ports collection.
  80 .Pp
  81 Each package name is printed, along with a one-character status flag:
  82 .Bl -tag -width indent
  83 .It Li =
  84 The installed version of the package is current.
  85 .It Li \&<
  86 The installed version of the package is older than the current version.
  87 .It Li \&>
  88 The installed version of the package is newer than the current version.
  89 This situation can arise with an out-of-date index file, or when
  90 testing new ports.
  91 .It Li \&?
  92 The installed package does not appear in the index.
  93 This could be due to an out of date index or a package taken from a PR
  94 that has not yet been committed.
  95 .It Li *
  96 There are multiple versions of a particular software package
  97 listed in the index file.
  98 Examples from the
  99 .Fx
 100 ports collection are the Tcl toolkit or the
 101 .Tn EMACS
 102 editor.
 103 .It Li \&!
 104 The installed package exists in the index but for some reason,
 105 .Nm
 106 was unable to compare the version number of the installed package
 107 with the corresponding entry in the index.
 108 .El
 109 .Sh OPTIONS
 110 The
 111 .Nm
 112 utility supports several command-line arguments:
 113 .Bl -tag -width indent
 114 .It Fl c
 115 Enable commands output.  Commands output includes the commands you should
 116 type to update your installed packages to the latest versions in the ports
 117 system.
 118 This feature does
 119 .Bf Em
 120 not
 121 .Ef
 122 constitute an automated packages updating system.
 123 The output of this command
 124 .Bf Em
 125 must
 126 .Ef
 127 be edited, in order to avoid destroying dependencies between installed
 128 packages.
 129 .It Fl d
 130 Enable debugging output.
 131 .It Fl h
 132 Print help message.
 133 .It Fl l
 134 Limit the output to those packages whose status flag matches the
 135 character(s) in
 136 .Ar limchar .
 137 More than one character can be specified in
 138 .Ar limchar .
 139 Note that because some of the status flag characters are also special
 140 to the shell, it is best to quote
 141 .Ar limchar
 142 with single quotes.
 143 .It Fl L
 144 Limit the output to those packages whose status flag doesn't match
 145 .Ar limchar .
 146 You may specify more than one character to match in
 147 .Ar limchar .
 148 Note that because some of the status flag characters are also special
 149 to the shell, it is best to quote
 150 .Ar limchar
 151 with single quotes.
 152 .It Fl s
 153 Limit the output to those packages whose names match a given
 154 .Ar string .
 155 .It Fl t
 156 Test a pair of version number strings and exit.
 157 The output consists of one of the single characters
 158 .Li =
 159 (equal),
 160 .Li \&<
 161 (right-hand number greater), or
 162 .Li \&>
 163 (left-hand number greater) on standard output.
 164 This flag is mostly useful for scripts or for testing.
 165 .It Fl v
 166 Enable verbose output.  Verbose output includes some English-text
 167 interpretations of the version number comparisons, as well as the
 168 version numbers compared for each package.  Non-verbose output is
 169 probably easier for programs or scripts to parse.
 170 .It Ar index
 171 Specify the index to be used as a basis of comparison.  This index can
 172 be specified as a filename (in the local filesystem) or a URL.  Any
 173 URL understandable by
 174 .Xr fetch 1
 175 can be used here.  If no
 176 .Ar index
 177 file is specified on the command line,
 178 .Pa /usr/ports/INDEX
 179 is used.
 180 .El
 181 .Sh SEE ALSO
 182 .Xr fetch 1 ,
 183 .Xr pkg_add 1 ,
 184 .Xr pkg_create 1 ,
 185 .Xr pkg_delete 1 ,
 186 .Xr pkg_info 1
 187 .Sh FILES
 188 .Bl -tag -width /usr/ports/INDEX -compact
 189 .It Pa /usr/ports/INDEX
 190 Default index file.
 191 .El
 192 .Sh EXAMPLES
 193 The following is a typical invocation of the
 194 .Nm
 195 command, which checks the installed packages against the local ports
 196 index file:
 197 .Pp
 198 .Dl % pkg_version -v
 199 .Pp
 200 The command below generates a report against
 201 the version numbers in the on-line ports collection:
 202 .Pp
 203 .Dl % pkg_version ftp://ftp.FreeBSD.org/pub/FreeBSD/branches/-current/ports/INDEX
 204 .Pp
 205 The command below generates a file of commands to run to update the installed
 206 files.
 207 These commands must
 208 .Bf Em
 209 not
 210 .Ef
 211 be run without suitable editing.
 212 They should be treated as suggestions, and may need to be reordered
 213 to account for dependencies between installed packages, or may need to
 214 be disregarded if multiple versions of an installed package can coexist.
 215 Blindly running the output of this command may leave a system in an
 216 unusable state.
 217 .Pp
 218 .Dl % pkg_version -c > do_update
 219 .Pp
 220 The following command compares two package version strings:
 221 .Pp
 222 .Dl % pkg_version -t 1.5 1.5.1
 223 .Sh AUTHORS
 224 .An Bruce A. Mah Aq bmah@FreeBSD.org
 225 .Sh CONTRIBUTORS
 226 .An Nik Clayton Aq nik@FreeBSD.org ,
 227 .An Dominic Mitchell Aq dom@palmerharvey.co.uk ,
 228 .An Mark Ovens Aq marko@FreeBSD.org ,
 229 .An Doug Barton Aq DougB@gorean.org ,
 230 .An Akinori MUSHA Aq knu@FreeBSD.org
 231 .Sh BUGS
 232 The commands output feature is
 233 .Bf Em
 234 not
 235 .Ef
 236 an automated ports/packages updating system.
 237 It does not even attempt to handle dependencies between installed
 238 packages correctly, and can produce incorrect results if multiple
 239 versions of a package can coexist on a system.
 240 .Pp
 241 Commands output assumes you install new software using the ports system,
 242 rather than using
 243 .Xr pkg_add 1 .