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$
  27 .Dd July 17, 1998
  28 .Dt PKG_VERSION 1
  29 .Os FreeBSD
  30 .Sh NAME
  31 .Nm pkg_version
  32 .Nd summarize installed versions of packages
  33 .Sh SYNOPSIS
  34 .Nm pkg_version
  35 .Op Fl cdhv
  36 .Op Ar index
  37 .Sh DESCRIPTION
  38 The
  39 .Nm
  40 command is used to produce a report of non-base software packages
  41 installed using the
  42 .Xr pkg_add 1
  43 command.  Version numbers are compared against an
  44 index file, to see which packages might need updating.
  45 .Pp
  46 Each package name is printed, along with a one-character status flag:
  47 .Bl -tag -width indent
  48 .It Li =
  49 The installed version of the package matches the index.
  50 .It Li <
  51 The installed version of the package is older than the version listed
  52 in the index.
  53 .It Li >
  54 The installed version of the package is newer than listed in the
  55 index.
  56 .It Li ?
  57 The relationship between the installed version of a package and the
  58 index file could not be determined.  A common reason for this message
  59 is that there are multiple versions of a particular software package
  60 installed, or that multiple versions are listed in the index file.
  61 Examples from the
  62 .Fx 2.2.6
  63 ports collection are the Tcl toolkit or the
  64 .Tn EMACS
  65 editor.
  66 .Sh OPTIONS
  67 .Nm
  68 supports several command-line arguments:
  69 .Bl -tag -width indent
  70 .It Fl c
  71 Enable commands output.  Commands output includes the commands you should
  72 type to update your installed packages to the latest versions in the ports
  73 system.
  74 .It Fl d
  75 Enable debugging output.
  76 .It Fl h
  77 Print help message.
  78 .It Fl v
  79 Enable verbose output.  Verbose output includes some English-text
  80 interpretations of the version number comparisons, as well as the
  81 version numbers compared for each package.  Non-verbose output is
  82 probably easier for programs or scripts to parse.
  83 .It Ar index
  84 Specify the index to be used as a basis of comparison.  This index can
  85 be specified as a filename (in the local filesystem) or a URL.  Any
  86 URL understandable by
  87 .Xr fetch 1
  88 can be used here.  If no
  89 .Ar index
  90 file is specified on the command line,
  91 .Pa /usr/ports/INDEX
  92 is used.
  93 .El
  94 .Sh SEE ALSO
  95 .Xr fetch 1 ,
  96 .Xr pkg_add 1 ,
  97 .Xr pkg_create 1 ,
  98 .Xr pkg_delete 1 .
  99 .Sh FILES
 100 .Bl -tag -width /usr/ports/INDEX -compact
 101 .It Pa /usr/ports/INDEX
 102 Default index file.
 103 .El
 104 .Sh EXAMPLES
 105 The following is a typical invocation of the
 106 .Nm
 107 command, which checks the installed packages against the local ports
 108 index file:
 109 .Pp
 110 .Dl % pkg_version -v
 111 .Pp
 112 The command below generates a report against
 113 the version numbers in the on-line ports collection:
 114 .Pp
 115 .Dl % pkg_version ftp://ftp.freebsd.org/pub/FreeBSD/ports-current/INDEX
 116 .Pp
 117 The command below generates a file of commands to run to update the installed
 118 files. It is
 119 .Bf Em
 120 not
 121 .Ef
 122 suggested that you run these commands automatically. Always review the
 123 suggestions, and then cut-and-paste (or retype) the commands you want to run.
 124 .Pp
 125 .Dl % pkg_version -c > do_update
 126 .Sh AUTHOR
 127 .An Bruce A. Mah Aq bmah@ca.sandia.gov
 128 .Sh CONTRIBUTORS
 129 .An Nik Clayton Aq nik@freebsd.org
 130 .Sh BUGS
 131 There should be a better way of dealing with packages that
 132 can have more than one installed version.
 133 .Pp
 134 Patch levels aren't handled
 135 very well (i.e. version numbers of the form 1.2p3 or 1.2pl3).
 136 .Pp
 137 Updates to packages
 138 that don't change the version number (e.g. small delta bugfixes in the
 139 package/port itself) aren't detected.
 140 .Pp
 141 Commands output doesn't know about dependencies between packages. For
 142 example, you might have two versions of Tcl installed because two other
 143 packages require the different versions.
 144 .Nm
 145 will suggest removing the out-of-date version.
 146 .Pp
 147 Commands output assumes you install new software using the ports system,
 148 rather than using
 149 .Xr pkg_add 1 .