PORTUPGRADE(1) BSD General Commands Manual PORTUPGRADE(1)NAME
portupgrade, portinstall — tools to upgrade installed packages or install
new ones via ports or packages
SYNOPSIS
portupgrade [-habcCDDefFiknNOpPPqrRsuvwWy] [-A command] [-B command]
[-l file] [-L format] [-S command] [-x pkgname_glob]
[[-o origin] [-m make_args] [-M make_env] pkgname_glob ...]
DESCRIPTION
The portupgrade command is used to upgrade installed packages via ports
or packages. The portinstall command is equivalent to portupgrade -N.
Before reading these instructions, you must understand that a port/pack‐
age can have the following two types of related ports/packages:
required Ports/packages that a port/package needs for it to be built
and/or run. Port Makefiles refer to this type of ports/pack‐
ages using the BUILD_DEPENDS and RUN_DEPENDS macros, respec‐
tively.
dependent Ports/packages that need this port/package.
When portupgrade deals with multiple packages, it automatically sorts the
packages in dependency order using the equivalent of tsort(1).
WARNING
· Please read this manual page carefully and understand what you are
doing with portupgrade.
· When the tools suggest running “pkgdb -F”, run it. Upgrade a certain
number of packages at once with an inconsistent package database will
surely cause bad results.
· Since portupgrade allows you to upgrade your installed packages with‐
out rebuilding and reinstalling dependent packages, upgraded packages
may occasionally cause binary incompatibilities. To cope with this
situation, use the -f, -r and -R options as necessary.
· Do not abort portupgrade while it is updating the package database,
or it will leave you a half modified, inconsistent database. Even if
you do not do anything wrong, a package database may get corrupt
somehow when it is heavily updated. In such cases, run “pkgdb -fu”
to rebuild the database and rescue the tools from coredumping. If it
makes no effect, remove a database file (/var/db/pkg/pkgdb.db) and
rerun the command.
· Do not be lazy about backing up your precious data and configuration
files, including the package database in “/var/db/pkg”.
OPTIONS
The following command line arguments are supported:
pkgname_glob Specify one of these: a full pkgname, a pkgname
without version, a shell glob pattern in which you
can use wildcards ‘*’, ‘?’, and an extended regu‐
lar expression preceded by a colon ‘:’, or a date
range specification preceded by either ‘<’ or ‘>’.
See pkg_glob(1) for details and concrete examples.
-h
--help Show help and exit.
-a
--all Do with all the installed packages. Equivalent to
specify '*' as pkgname_glob.
-A CMD
--afterinstall CMD Run the specified command as root after each
installation.
-b
--backup-packages Keep backup packages of the old versions.
--batch Run an upgrading process in a batch mode (with
BATCH=yes). This will only process ports in a
100% automated way, without requiring any user
interaction. Options dialogs will not be pre‐
sented. Also see -c and -C. See ports(7) for
more details.
-B CMD
--beforebuild CMD Run the specified command before each build. If
the command exits in failure, the port/package
will be skipped. Here is some typical uses:
portupgrade -B 'cvs update' 'gnome*'
portupgrade -B 'ports_glob -M $(pwd) | (cd
../..; xargs cvs up)' slave/port
portupgrade -aB 'test ! `make -V
IS_INTERACTIVE`'
-c
--config Run “make config-conditional” before everything
for all tasks.
-C
--force-config Run “make config” before everything for all tasks.
-D
--distclean Delete failed distfiles and retry if checksum
fails. Specified twice, do “make distclean”
before each fetch or build.
-e
--emit-summaries Emit summary info after each port processing.
-f
--force Force the upgrade of a package even if it is to be
a downgrade or just a reinstall of the same ver‐
sion, or the port is held by user using the
HOLD_PKGS variable in pkgtools.conf.
-F
--fetch-only Only fetch distfiles or packages (if -P is speci‐
fied), do not build, upgrade or install anything.
This is useful if you want to download all the
needed distfiles or packages at once in advance of
installing or upgrading.
By default, if a port or a package fails to build
or install, its dependents will be skipped.
--ignore-moved Do not read MOVED file.
-i
--interactive Turn on interactive mode. You are asked for
approval before each suggested installation or
upgrade. This option implies -v.
-k
--keep-going Force the upgrade of a package even if some of the
requisite packages have failed to upgrade in
advance.
-l FILE
--results-file FILE Specify a file name to save the results to. By
default, portupgrade does not save results as a
file.
-L FORMAT
--log-file FORMAT Specify a printf(3) style format to determine the
log file name for each port. “%s::%s” is appended
if it does not contain a ‘%’. Category and port‐
name are given as arguments, in the order named.
-m
--make-args Specify arguments to append to each make(1) com‐
mand line.
-M
--make-env Specify arguments to prepend to each make(1) com‐
mand line.
-n
--noexecute Do not actually install, upgrade or fetch any
packages; just show what would be done. This
option implies -v and negates -i and -y.
-N
--new Install a new port/package when a specified pack‐
age is not installed. Prior to the installation a
new port/package, all the required packages are
upgraded.
If this option is specified, you can specify a
portorigin glob as well as a pkgname glob to spec‐
ify which port to install. See portsdb(1) for the
details of the ‘portorigin glob’.
This option makes portupgrade behave as if it were
called as portinstall.
-o ORIGIN
--origin ORIGIN Specify a port to upgrade the following package
with.
-O
--omit-check Omit sanity checks for dependencies. By default,
portupgrade checks if all the packages to upgrade
have consistent dependencies, though it takes
extra time to calculate dependencies. If you are
sure you have run “pkgdb -F” in advance, you can
specify this option to omit the sanity checks.
-p
--package Build a package when each specified port is
installed or upgraded. If a package is upgraded
and its dependent packages are given from the com‐
mand line (including the case where -r is speci‐
fied), build packages for them as well.
-P
--use-packages Use packages instead of ports whenever available.
portupgrade searches the local directories listed
in PKG_PATH for each package to install or upgrade
the current installation with, and if none is
found, pkg_fetch(1) is invoked to fetch one from a
remote site. If it does not work either, the port
is used.
However, the source will still be used if the port
is listed in USE_PORTS_ONLY variable in
pkgtools.conf.
-PP
--use-packages-only Never use the port even if a package is not avail‐
able either locally or remotely, although you
still have to keep your ports tree up-to-date so
that portupgrade can check out what the latest
version of each port is.
-q
--quiet Do not display a message when -N specified and
there is already installed package.
--noconfig Do not read the configuration file -
$PREFIX/etc/pkgtools.conf.
-r
--recursive Act on all those packages depending on the given
packages as well.
-R
--upward-recursive Act on all those packages required by the given
packages as well. (When specified with -F, fetch
recursively, including the brand new, uninstalled
ports that an upgraded port requires)
-s
--sudo Run commands under sudo(8) where needed.
-S CMD
--sudo-command CMD Specify an alternative to sudo(8). e.g. “'su
root -c %s '” (default: sudo)
-u
--uninstall-shlibs Do not preserve old shared libraries. By default,
portupgrade preserves shared libraries on unin‐
stallation for safety. See the pkg_deinstall(1)
manpage and check out the -P option for details.
-v
--verbose Turn on verbose output.
-w
--noclean Do not “make clean” before each build.
-W
--nocleanup Do not “make clean” after each installation.
--without-env-upgrade Do not set UPGRADE_* environment variables.
-x GLOB
--exclude GLOB Exclude packages matching the specified glob pat‐
tern. Exclusion is performed after recursing
dependency in response to -r and/or -R, which
means, for example, the following command will
upgrade all the packages depending on XFree86 but
leave XFree86 as it is:
portupgrade -rx XFree86 XFree86
-y
--yes Answer yes to all the questions. This option
implies -v and negates -n.
TECHNICAL DETAILS
portupgrade upgrades installed packages via ports or packages without
necessarily having to reinstall required or dependent packages by adjust‐
ing the package registry database.
The procedures it takes are briefly shown as below:
1. If -P is not given, jump to 4. Otherwise search the local
directories listed in PKG_PATH for a newer package tarball.
If found, jump to 5.
2. Fetch the latest package from a remote site using
pkg_fetch(1). If the fetched package is the latest, jump to
5. If -P is given twice (i.e. -PP) and the fetched package
is not the latest but at least newer than the current instal‐
lation, jump to 5.
3. If -P is given twice (i.e. -PP), stop the task.
4. Build the corresponding port of the given installed package.
5. Fix the dependency information of the packages that depend on
the given package.
6. Back up the current installation of the given package using
pkg_create(1). Note that the backup tarball will be very
large if the package is a big monster like XFree86. Please
ensure you have sufficient disk space (refer to the ENVIRON‐
MENT section to know where) to save the backup tarball. (Per‐
haps a new option to omit backups will be added in the future)
7. Back up the current package registration files of the given
package.
8. Uninstall the given package forcibly, preserving shared
libraries unless -u is specified.
9. Install the new version via ports or packages, depending on
the conditions in 1, 2 and 3.
10. If the installation fails,
10.1. Restore the old installation backed up in 6.
10.2. Restore the old package registration files
backed up in 7.
10.3. Revert the dependency information fixed in 5.
11. Remove the dependencies obsoleted in this upgrade.
12. Run “portsclean -L” to delete duplicate libraries and put away
old libraries.
13. Run “pkgdb -aF” to fix up stale dependencies and reconstruct
+REQUIRED_BY files.
EXAMPLES
· Upgrade glib:
portupgrade glib
As you see, you can omit version numbers. If multiple versions are
installed, each of them is upgraded unless they share a port origin.
(For example you may probably have foo-1.02 and foo-1.03 recorded
somehow; run “pkgdb -F” to fix the situation)
· Upgrade XFree86 and Mesa, passing -DWANT_GGI to make(1) for Mesa:
portupgrade XFree86 -m '-DWANT_GGI' Mesa
-m / --make-args is the option to specify options to pass to make(1).
· Upgrade all the GNOME packages, keeping build logs in
“/var/tmp/portupgrade-<category>::<portname>.log”:
portupgrade -L /var/tmp/portupgrade-%s::%s.log '*gnome*'
You can use the wildcards as in sh(1). Perl compatible extended reg‐
ular expressions are also available by prepending a colon ‘’: to a
pattern. In the above case, you could type: :gnome.
-L / --log-prefix is the option to tell portupgrade to keep the build
log as a file for each port build. Regardless of the option,
portupgrade always watches the build output of each port and when a
build fails it guesses the reason why it has failed.
· Upgrade sawfish and all that sawfish depends on, building binary
packages for the upgraded packages, with the verbose mode on:
portupgrade -Rpv sawfish
-R / --upward-recursive is the option to tell portupgrade to recurse
upwards through dependencies. In the above case, rep-gtk, librep,
imlib, gnomelibs, XFree86 etc. would be upgraded.
-p / --package is the option to tell portupgrade to build a binary
package while it upgrades a package.
-v / --verbose is the option to turn the verbose mode on.
· Upgrade glib and all that depend on it, confirming each upgrade:
portupgrade -ri glib
-r / --recursive is the option to tell portupgrade to recurse down‐
wards through dependencies. In the above case, gtk and all GNOME
related packages would be upgraded.
-i / --interactive is the option to tell portupgrade to ask you for
approval before performing something important.
· Rebuild and reinstall all ports that depend on sdl, but not sdl
itself:
portupgrade -rfx sdl sdl
-f / --force is the option to force portupgrade to upgrade a package
even if it does not seem to be needed judging from a version compari‐
son.
-x / --exclude is the option to specify an exclusion pattern.
· Rebuild and reinstall all that ports that were installed prior to the
date 2001-09-20:
portupgrade -f '<2001-09-20'
You can also select packages by a date range.
· Rebuild and reinstall all the dependent packages of png that were
installed prior to png:
portupgrade -fr png -x '>=png'
You may use a package to specify a date.
· Fetch all the distfiles that are needed to upgrade all the installed
packages at once, but do not upgrade anything yet:
portupgrade -aFR
-a / --all is equivalent to specifying an ‘*’.
-F / --fetch is the option to tell portupgrade to not upgrade any‐
thing but just fetch distfiles.
It is necessary to specify -R in addition to -a because some of the
upgraded ports might require new ports that are not installed yet.
· Replace ghostscript-gnu with ghostscript-afpl:
portupgrade -o print/ghostscript-afpl ghostscript-gnu
-o / --origin was originally the option to supply a missing origin of
an outdated package before FreeBSD 4.2, but this example shows
another useful usage. Use portupgrade like this, and all the depen‐
dencies on the old package (ghostscript-gnu) will be succeeded to the
new one (ghostscript-afpl) cleanly, without leaving inconsistency.
· Upgrade glib using a package. If necessary, download one from a
remote ftp site:
portupgrade -P glib
-P / --use-packages is the option to tell portupgrade to use packages
instead of ports where available.
· Perform a massive binary upgrade using the packages stored on a CD-
ROM, but before that, figure out what will be upgraded:
env PKG_PATH=/mnt/cdrom/packages/All portupgrade -anPP
-n / --noexecute is the option to tell portupgrade not to commit any
upgrade but just show what would be done.
Double -P tells portupgrade to use packages only; portupgrade will
not upgrade a package if a package file (*.tbz) to upgrade the pack‐
age with is not available.
If you do not want portupgrade to download packages which are not on
the CD-ROM, set PKG_FETCH to something like “/bin/false”.
TIPS
· After performing a binary upgrade, it is strongly recommended that
you run “pkgdb -F” to fix broken dependencies introduced by the newly
installed packages.
· Do a massive network binary upgrade:
portupgrade -aPPR
· When in doubt, use the portupgrade options such as -n and -i to see
what would be done, or use pkg_glob(1) to see how it expands glob
patterns.
· To perform upgrades effectively and correctly, remember to run
pkgdb(1) with -F on occasions to fix dependency discrepancies, and
run portsdb(1) with -Uu every time you CVSup the ports tree to keep
your ports INDEX database up-to-date in sync with the tree.
· To check for available upgrades, give portversion(1) a try instead of
pkg_version(1). It has comparable usage with pkg_version(1) but runs
much faster. Also the output script of “portversion -c” utilizes
portupgrade(1) for upgrading.
· To deinstall packages, give pkg_deinstall(1) a try instead of
pkg_delete(1). It is a wrapper of pkg_delete(1) with additional fea‐
tures, such as recursive deinstall and shared library preservation.
· To clean unreferenced distfiles, working directories and old shared
libraries, use portsclean(1).
· To track the change history of a port, use portsvnweb(1).
ENVIRONMENT
PKG_DBDIR Alternative location for the installed package data‐
base. Default is “/var/db/pkg”.
PORTSDIR Alternative location for the ports tree. Default is
“/usr/ports”.
PORTS_INDEX Alternative location for the ports INDEX file. Default
is “$PORTSDIR/INDEX”.
PORTS_DBDIR Alternative location for the ports database files.
Default is “$PORTSDIR”.
PKG_TMPDIR
TMPDIR (In that order) Temporary directory where portupgrade
attempts to create backup files. If neither is
defined, “/var/tmp” is used. Note that this directory
must have enough free space when upgrading a big pack‐
age. (See the TECHNICAL DETAILS above)
PACKAGES Base directory where portupgrade creates packages.
Default is “$PORTSDIR/packages”.
PKG_PATH A list of directories where portupgrade searches for
packages, separated by colons. Default is
“$PACKAGES/All”.
PKG_SUFX Suffix for packages. Default is the value defined in
bsd.port.mk or /etc/make.conf.
PKGTOOLS_CONF Configuration file for the pkgtools suite. Default is
“$PREFIX/etc/pkgtools.conf”.
PORTUPGRADE Default options for portupgrade (e.g. -v)
UPGRADE_TOOL The environment variable is set to upgrade tool name.
Always is set to “portupgrade”.
UPGRADE_PORT The variable is set to a port name and version (as PKG‐
NAME make variable) which is upgraded.
UPGRADE_PORT_VER A version number extracted from UPGRADE_PORT (it's the
same as in PKGVERSION make variable).
FILES
/var/tmp Temporary directory for creating backup files,
if environmental variables PKG_TMPDIR or
TMPDIR do not point to a suitable directory.
/var/db/pkg Default location of the installed package
database.
/usr/ports Default location of the ports tree and the
ports database files.
/usr/ports/packages/All Default location of backup packages saved with
-b.
$PREFIX/etc/pkgtools.conf Default location of the pkgtools configuration
file.
SEE ALSOpkg_add(1), pkg_deinstall(1), pkg_delete(1), pkg_glob(1), pkg_info(1),
pkg_sort(1), pkgdb(1), portsvnweb(1), ports_glob(1), portsclean(1),
portsdb(1), portversion(1), pkgtools.conf(5), ports(7)AUTHORS
Akinori MUSHA ⟨knu@iDaemons.org⟩
Sergey Matveychuk ⟨sem@FreeBSD.org⟩
Stanislav Sedov ⟨stas@FreeBSD.org⟩
Bryan Drewery ⟨bdrewery@FreeBSD.org⟩
BUGS
SUSP (^Z) does not work during a build/install.
Sometimes a database may get corrupt and the pkgtools commands start to
abort due to segmentation fault. In such cases, run “pkgdb -fu” to
rebuild the database, and the problems will go away. If the command
failed itself, remove a database file (/var/db/pkg/pkgdb.db) and run it
again.
Some third-party or hand-made packages have invalid package names which
make portupgrade and the related tools angry. To completely hide the
existence of a package from them, put (just touch(1)) a dummy file named
"+IGNOREME" in the package directory.
FreeBSD June 17, 2013 FreeBSD
