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

FreeBSD Manual Pages

  
 
  

home | help
PORTUPGRADE(1)		    General Commands Manual		PORTUPGRADE(1)

NAME
       portupgrade,  portinstall -- tools to upgrade installed packages	or in-
       stall 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/package  can  have	the following two types	of related ports/pack-
       ages:
       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.

       When  portupgrade  deals	with multiple packages,	it automatically sorts
       the packages in dependency order	using the equivalent of	tsort(1).

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	 data-
	   base	will surely cause bad results.

       o   Since  portupgrade  allows  you  to upgrade your installed packages
	   without 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 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.

       o   Do  not  be lazy about backing up your precious data	and configura-
	   tion	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  con-
			      crete 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 in-
			      stallation.

       -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" be-
			      fore 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
			      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 spec-
			      ified),  do  not	build, upgrade or install any-
			      thing.  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 ap-
			      proval before each suggested installation	or up-
			      grade.  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 or-
			      der 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)
			      command 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
			      package is not installed.	 Prior to the  instal-
			      lation  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'.

			      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 de-
			      fault, 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 in-
			      stalled 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	avail-
			      able.  portupgrade searches the  local  directo-
			      ries  listed in PKG_PATH for each	package	to in-
			      stall 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
			      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
       --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,	 unin-
			      stalled 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 de-
			      fault, 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.

       -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
			      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  ad-
       justing 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  in-
		  stallation, 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.
		  (Perhaps 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  li-
		  braries 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  ori-
	   gin.	  (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

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

       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 re-
	   curse 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 it-
	   self:

		 portupgrade -rfx sdl sdl

	   -f  / --force is the	option to force	portupgrade to upgrade a pack-
	   age even if it does not seem	to be needed judging  from  a  version
	   comparison.

	   -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 in-
	   stalled 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 de-
	   pendencies on the old package (ghostscript-gnu) will	 be  succeeded
	   to  the  new	one (ghostscript-afpl) cleanly,	without	leaving	incon-
	   sistency.

       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 pack-
	   ages	instead	of ports where available.

       o   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
	   package 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
       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"  uti-
	   lizes 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
	   features,  such as recursive	deinstall and shared library preserva-
	   tion.

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

       o   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.   De-
			 fault 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  de-
			 fined,	 "/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".

       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
			 PKGNAME 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	direc-
				  tory.

       /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  configura-
				  tion file.

SEE ALSO
       pkg_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 re-
       build  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			PORTUPGRADE(1)

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:
<https://man.freebsd.org/cgi/man.cgi?query=portupgrade&sektion=1&manpath=FreeBSD+14.0-RELEASE+and+Ports>

home | help