Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PORTUPGRADE(1)		FreeBSD	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.

WARNING
     +o	 Please	read this manual page carefully	and understand what you	are
	 doing with portupgrade.

     +o	 When the tools	suggest	running	``pkgdb	-F'', run it.  Upgrade a cer-
	 tain number of	packages at once with an inconsistent package database
	 will surely cause bad results.

     +o	 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.

     +o	 Do not	abort portupgrade while	it is updating the package database,
	 or it will leave you a	half modified, inconsistent database.  Even if
	 you don't do anything wrong, a	package	database may get corrupt some-
	 how 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.

     +o	 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).

     -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	portname 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 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	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'.

     -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	doesn't	work either, the port
			    is used.

     -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
     +o	 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)

     +o	 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).

     +o	 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.

     +o	 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.

     +o	 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.

     +o	 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.

     +o	 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.

     +o	 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.

     +o	 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.

     +o	 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.

     +o	 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.

     +o	 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	pack-
	 age 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
     +o	 After performing a binary upgrade, it is strongly recommended that
	 you run ``pkgdb -F'' to fix broken dependencies introduced by the
	 newly installed packages.

     +o	 Do a massive network binary upgrade:

	       portupgrade -aPPR

     +o	 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.

     +o	 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.

     +o	 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.

     +o	 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.

     +o	 To clean unreferenced distfiles, working directories and old shared
	 libraries, use	portsclean(1).

     +o	 To track the change history of	a port,	use portcvsweb(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 direc-
		       tory 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''.

     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 ALSO
     pkg_add(1), pkg_deinstall(1), pkg_delete(1), pkg_glob(1), pkg_info(1),
     pkg_sort(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>
     Sergey Matveychuk <sem@FreeBSD.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.  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 15, 2001			       FreeBSD

NAME | SYNOPSIS | DESCRIPTION | WARNING | OPTIONS | TECHNICAL DETAILS | EXAMPLES | TIPS | ENVIRONMENT | FILES | SEE ALSO | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=portupgrade&sektion=1&manpath=FreeBSD+Ports>

home | help