243 lines
7.5 KiB
Groff
243 lines
7.5 KiB
Groff
.\"
|
|
.\" Copyright 1998 Bruce A. Mah
|
|
.\"
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.Dd July 17, 1998
|
|
.Dt PKG_VERSION 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pkg_version
|
|
.Nd summarize installed versions of packages
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl cdhv
|
|
.Op Fl l Ar limchar
|
|
.Op Fl L Ar limchar
|
|
.Op Fl s Ar string
|
|
.Op Ar index
|
|
.Nm
|
|
.Op Fl t Ar version1 version2
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
command is used to produce a report of non-base software packages
|
|
installed using the
|
|
.Xr pkg_add 1
|
|
command.
|
|
.Pp
|
|
Each package's version number is checked against one of two sources to
|
|
see if that package may require updating. If the package contains
|
|
information about its origin in the
|
|
.Fx
|
|
ports tree, and a version number can be determined from the port's
|
|
.Pa Makefile ,
|
|
then the version number from the
|
|
.Pa Makefile
|
|
will be used to determine whether the installed package is up-to-date
|
|
or requires updating.
|
|
.Pp
|
|
If no origin for a package can be found, or if the port's
|
|
.Pa Makefile
|
|
cannot be located,
|
|
.Nm
|
|
will search for the package in the ports collection index file
|
|
(typically
|
|
.Pa /usr/ports/INDEX ) .
|
|
Any matching version number(s) there will be used to determine whether
|
|
the installed package is up-to-date or requires updating.
|
|
.Pp
|
|
Generally, using the version number from a port's
|
|
.Pa Makefile
|
|
will provide a more accurate result, since, unlike the index file, it
|
|
provides an unambiguous current version number, even when multiple
|
|
versions of a port exist in the ports collection.
|
|
Moreover, the ports collection index file is only updated at
|
|
intervals, meaning that it may not completely reflect the version
|
|
numbers of the software contained in the ports collection.
|
|
.Pp
|
|
Each package name is printed, along with a one-character status flag:
|
|
.Bl -tag -width indent
|
|
.It Li =
|
|
The installed version of the package is current.
|
|
.It Li \&<
|
|
The installed version of the package is older than the current version.
|
|
.It Li \&>
|
|
The installed version of the package is newer than the current version.
|
|
This situation can arise with an out-of-date index file, or when
|
|
testing new ports.
|
|
.It Li \&?
|
|
The installed package does not appear in the index.
|
|
This could be due to an out of date index or a package taken from a PR
|
|
that has not yet been committed.
|
|
.It Li *
|
|
There are multiple versions of a particular software package
|
|
listed in the index file.
|
|
Examples from the
|
|
.Fx
|
|
ports collection are the Tcl toolkit or the
|
|
.Tn EMACS
|
|
editor.
|
|
.It Li \&!
|
|
The installed package exists in the index but for some reason,
|
|
.Nm
|
|
was unable to compare the version number of the installed package
|
|
with the corresponding entry in the index.
|
|
.El
|
|
.Sh OPTIONS
|
|
The
|
|
.Nm
|
|
utility supports several command-line arguments:
|
|
.Bl -tag -width indent
|
|
.It Fl c
|
|
Enable commands output. Commands output includes the commands you should
|
|
type to update your installed packages to the latest versions in the ports
|
|
system.
|
|
This feature does
|
|
.Bf Em
|
|
not
|
|
.Ef
|
|
constitute an automated packages updating system.
|
|
The output of this command
|
|
.Bf Em
|
|
must
|
|
.Ef
|
|
be edited, in order to avoid destroying dependencies between installed
|
|
packages.
|
|
.It Fl d
|
|
Enable debugging output.
|
|
.It Fl h
|
|
Print help message.
|
|
.It Fl l
|
|
Limit the output to those packages whose status flag matches the
|
|
character(s) in
|
|
.Ar limchar .
|
|
More than one character can be specified in
|
|
.Ar limchar .
|
|
Note that because some of the status flag characters are also special
|
|
to the shell, it is best to quote
|
|
.Ar limchar
|
|
with single quotes.
|
|
.It Fl L
|
|
Limit the output to those packages whose status flag doesn't match
|
|
.Ar limchar .
|
|
You may specify more than one character to match in
|
|
.Ar limchar .
|
|
Note that because some of the status flag characters are also special
|
|
to the shell, it is best to quote
|
|
.Ar limchar
|
|
with single quotes.
|
|
.It Fl s
|
|
Limit the output to those packages whose names match a given
|
|
.Ar string .
|
|
.It Fl t
|
|
Test a pair of version number strings and exit.
|
|
The output consists of one of the single characters
|
|
.Li =
|
|
(equal),
|
|
.Li \&<
|
|
(right-hand number greater), or
|
|
.Li \&>
|
|
(left-hand number greater) on standard output.
|
|
This flag is mostly useful for scripts or for testing.
|
|
.It Fl v
|
|
Enable verbose output. Verbose output includes some English-text
|
|
interpretations of the version number comparisons, as well as the
|
|
version numbers compared for each package. Non-verbose output is
|
|
probably easier for programs or scripts to parse.
|
|
.It Ar index
|
|
Specify the index to be used as a basis of comparison. This index can
|
|
be specified as a filename (in the local filesystem) or a URL. Any
|
|
URL understandable by
|
|
.Xr fetch 1
|
|
can be used here. If no
|
|
.Ar index
|
|
file is specified on the command line,
|
|
.Pa /usr/ports/INDEX
|
|
is used.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr fetch 1 ,
|
|
.Xr pkg_add 1 ,
|
|
.Xr pkg_create 1 ,
|
|
.Xr pkg_delete 1 ,
|
|
.Xr pkg_info 1
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/ports/INDEX -compact
|
|
.It Pa /usr/ports/INDEX
|
|
Default index file.
|
|
.El
|
|
.Sh EXAMPLES
|
|
The following is a typical invocation of the
|
|
.Nm
|
|
command, which checks the installed packages against the local ports
|
|
index file:
|
|
.Pp
|
|
.Dl % pkg_version -v
|
|
.Pp
|
|
The command below generates a report against
|
|
the version numbers in the on-line ports collection:
|
|
.Pp
|
|
.Dl % pkg_version ftp://ftp.FreeBSD.org/pub/FreeBSD/branches/-current/ports/INDEX
|
|
.Pp
|
|
The command below generates a file of commands to run to update the installed
|
|
files.
|
|
These commands must
|
|
.Bf Em
|
|
not
|
|
.Ef
|
|
be run without suitable editing.
|
|
They should be treated as suggestions, and may need to be reordered
|
|
to account for dependencies between installed packages, or may need to
|
|
be disregarded if multiple versions of an installed package can coexist.
|
|
Blindly running the output of this command may leave a system in an
|
|
unusable state.
|
|
.Pp
|
|
.Dl % pkg_version -c > do_update
|
|
.Pp
|
|
The following command compares two package version strings:
|
|
.Pp
|
|
.Dl % pkg_version -t 1.5 1.5.1
|
|
.Sh AUTHORS
|
|
.An Bruce A. Mah Aq bmah@FreeBSD.org
|
|
.Sh CONTRIBUTORS
|
|
.An Nik Clayton Aq nik@FreeBSD.org ,
|
|
.An Dominic Mitchell Aq dom@palmerharvey.co.uk ,
|
|
.An Mark Ovens Aq marko@FreeBSD.org ,
|
|
.An Doug Barton Aq DougB@gorean.org ,
|
|
.An Akinori MUSHA Aq knu@FreeBSD.org
|
|
.Sh BUGS
|
|
The commands output feature is
|
|
.Bf Em
|
|
not
|
|
.Ef
|
|
an automated ports/packages updating system.
|
|
It does not even attempt to handle dependencies between installed
|
|
packages correctly, and can produce incorrect results if multiple
|
|
versions of a package can coexist on a system.
|
|
.Pp
|
|
Commands output assumes you install new software using the ports system,
|
|
rather than using
|
|
.Xr pkg_add 1 .
|