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