PORTUPGRADE(1)

NAME
portupgrade, portinstall - tools to upgrade installed packages or install new ones via ports or packages

SYNOPSIS
portupgrade [-habcCDfFginNOpPPqrRsuvwWy] [-A command] [-B command] [-l file] [-L prefix] [-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/package 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/packages using the BUILD_DEPENDS and RUN_DEPENDS macros, respectively.
dependent
    Ports/packages that need this port/package.

WARNING

•   Please read this manual page carefully and understand what you are doing with portupgrade.

•   Never forget to run “pkgdb -F” before you upgrade a certain number of packages at once. An inconsistent package database will surely cause bad results.

•   Since portupgrade allows you to upgrade your installed packages without rebuilding and reinstalling dependent packages, an upgraded package 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. (although it is 100% safe to abort it while building a port)

•   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 regular 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. These are kept in a temporary directory. See PKG_TMPDIR and TMPDIR in the ENVIRONMENT section.

-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
--clean
    Do “make clean” before each build. This is the default behavior. See the -w option below.

-C
--cleanup
    Do “make clean” after each installation. This is the default behavior. See the -W option below.

-D
--distclean
    Do “make distclean” before each fetch or build.

-f
--force
    Force the upgrade of a package even if it is to be a downgrade or just a reinstall of the same version, 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 specified), 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.

-g
--go-on
    Force the upgrade of a package even if some of the requisite packages have failed to upgrade in advance.

    By default, if a port or a package fails to build or install, its dependents will be skipped.

-i
--interactive
    Turn on interactive mode. You are asked for approval before each suggested installation or upgrade. This option implies -v.

-l FILE
--log-results FILE
    Save the results as a file named FILE.

-L PREFIX
--log-prefix PREFIX
    Save each port's build & install log as a file with a prefix PREFIX. The full pathname will be “<PREFIX><category>::<portname>”.

-m
--make-args
    Specify arguments to append to each make(1) command line.

-M
--make-env
    Specify arguments to prepend to each make(1) command line.

-n
--noexecute
    Do not actually install or upgrade 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 package 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 specify which port to install. See portsdb(1) for the details of the ‘portorigin glob’.

-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 command line (including the case where -r is specified), 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 doesn't work either, the port is used.

-PP
--use-packages-only
    Never use the port even if a package is not available 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
--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 uninstallation 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. See the -c option above.

-W
--nocleanup
    Do not “make clean” after each installation. See the -C option above.

-x GLOB
--exclude GLOB
    Exclude packages matching the specified glob pattern. 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 adjusting 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 installation, 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.  Save the +REQUIRED_BY list of the given package.

7.  Back up the current installation of the given package using pkg_tarup(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 ENVIRONMENT section to know where) to save the backup tarball. (Perhaps a new option to omit backups will be added in the future)

8.  Back up the current package registration files of the given package.

9.  Uninstall the given package forcibly, preserving shared libraries unless -u is specified.

10. Install the new version via ports or packages, depending on the conditions in 1, 2 and 3.

11. If the installation fails,

    1.  Restore the old installation backed up in 7.

    2.  Restore the old package registration files backed up in 8.

    3.  Revert the dependency information fixed in 5.

12. Remove the dependencies obsoleted in this upgrade.

13. Restore the +REQUIRED_BY list saved in 6.

14. Run “portsclean -L” to delete duplicate libraries and put away old libraries.

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

    When portupgrade deals with multiple packages, it automatically sorts the packages in dependency order before everything.

    -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/log.<category>::<portname>”:

        portupgrade -L /var/tmp/log. '*gnome*'

    You can use the wildcards as in sh(1). Perl compatible extended regular 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 downwards 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 comparison.

    -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 anything 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 dependencies 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.

•   Let's perform a massive binary upgrade using the packages stored on a CD-ROM, but before that I want to 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 (*.tgz) to upgrade the package with is not available.

    If you don't 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 features, 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 portcvsweb(1).

ENVIRONMENT
PKG_DBDIR
    Alternative location for the installed package database. 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 package. (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”.

PKGTOOLS_CONF
    Configuration file for the pkgtools suite. Default is “$PREFIX/etc/pkgtools.conf”.

PORTUPGRADE
    Default options for portupgrade (e.g. -v)

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.

$PREFIX/etc/pkgtools.conf
    Default location of the pkgtools configuration file.

SEE ALSO
pkg_add(1), pkg_deinstall(1), pkg_delete(1), pkg_glob(1), pkg_info(1), pkg_sort(1), pkg_update(1), pkgdb(1), portcvsweb(1), ports_glob(1), portsclean(1), portsdb(1), portversion(1), pkgtools.conf(5), ports(7)

AUTHORS
Akinori MUSHA <knu@iDaemons.org>

BUGS
SUSP (^Z) doesn't 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.