Skip to content

portmaster(8) - FreeBSD Man Page

Command Section
PORTMASTER(8)		FreeBSD	System Manager's Manual		 PORTMASTER(8)

NAME
     portmaster	-- manage your ports without external databases	or languages

SYNOPSIS
     Common Flags: [--force-config -CGHKgntvw -[B|b] -[f|i] -[D|d]]
     [[[--packages|-P]|[--packages-only|-PP]] |	[--packages-build]]
     [--packages-if-newer] [--delete-build-only] [--always-fetch]
     [--local-packagedir=<path>] [--packages-local] [--delete-packages]
     [--no-confirm] [--no-term-title] [--no-index-fetch]
     [--index|--index-first|--index-only] [-m arguments	for make]
     [-x glob pattern to exclude from building]
     portmaster	[Common	Flags] full name of port directory in /var/db/pkg
     portmaster	[Common	Flags] full path to /usr/ports/foo/bar
     portmaster	[Common	Flags] glob pattern of directories from	/var/db/pkg

		PLEASE NOTE: Glob patterns now update every port that matches.
		This is	a change from pre-version-2.3 behavior.

     portmaster	[Common	Flags] [--update-if-newer] Multiple full names or
		paths from /usr/ports or /var/db/pkg, and/or multiple globs
		from /var/db/pkg
     portmaster	[Common	Flags]
		 . (Use	in /usr/ports/foo/bar to build that port)
     portmaster	[Common	Flags] -a
     portmaster	--show-work [-Gv] [-m args] <single port, as above>
     portmaster	[Common	Flags] -o <new port dir	in /usr/ports> <installed
		port>
     portmaster	[Common	Flags] [-R] -r name/glob of port in /var/db/pkg	(can
		be specified more than once)
     portmaster	-l
     portmaster	[--index-only [-t]] -L
     portmaster	--list-origins
     portmaster	[--force-config|-G] [-P|-PP] [-aftv] -F
     portmaster	[-n|y] [-b] [-D|d] -e name/glob	of a single port directory in
		/var/db/pkg
     portmaster	[-n|y] [-b] [-D|d] -s
     portmaster	[-n|y] [-t] --clean-distfiles
     portmaster	[-n|y] [--index|-index-only] --clean-packages
     portmaster	[-n|y] [--index|-index-only] [-v] --check-depends
     portmaster	[-n|y] [-v] --check-port-dbdir
     portmaster	-h|--help
     portmaster	--version

		The "glob" patterns mentioned above are	not regular expres-
		sions.	For example: "portmaster perl" would match every port
		directory name in /var/db/pkg that fits	the pattern
		"/var/db/pkg/perl*".

QUICK START GUIDE
     This manual contains a lot	of valuable information	about portmaster, and
     you should	read the entire	manual to give you a better idea about how it
     works and what choices are	available to you.  However in the interests of
     getting you started quickly please	see the	EXAMPLES section at the	end of
     the manual.

DESCRIPTION
     The portmaster utility is a tool for updating your	ports.	It does	not
     use an external database to track what you	have installed.	 Rather	it
     uses the existing ports infrastructure, including what is located in
     /var/db/pkg.  The focus of	this tool is to	keep the dependency tracking
     information for your ports	up to date.  This allows you to	safely update
     a specific	port without having to update all of the ports "above" it.  In
     the rare case where you do	need to	recompile ports	which depend on	a port
     you are updating, the -r option exists to accomplish this.

     By	default	portmaster updates the port you	specify	on the command line.
     This will occur whether there is a	new version for	it or not.  It will
     first recurse through the port and	all of its dependencies	(if any) to
     handle any	port OPTIONS via the 'make config' interface.  You will	be
     presented with an OPTIONS dialog if you have never	built the port before,
     or	if the OPTIONS have changed.  You can force dialogs for	all ports by
     using the --force-config option.

     While recursing through dependencies, if you are not using	any of the
     --packages* options, a 'make checksum' process will be launched in	the
     background	to either verify that the correct distfiles are	available or
     start downloading the new ones.  If you stop portmaster with ^C, an
     attempt will be made to kill off the child	processes started for this
     purpose.

     While checking dependencies if a port has CONFLICTS set they will be com-
     pared to your installed ports and if you already have an alternate	ver-
     sion of the dependency that is required by	the port you are building it
     will be used in place of the default dependency.

     When the config and dependency checking phase is over the user will be
     presented with a list of ports that will be installed and/or upgraded,
     and asked to approve before proceeding.  This behavior can	be suppressed
     with the --no-confirm option.

     If	the dependency check does not find a port that needs updating that
     step will be skipped prior	to building the	port(s)	specified on the com-
     mand line.	 In addition to	this optimization, information about up-to-
     date dependencies,	choices	made on	which ports to build for interactive
     mode, and ports already visited for 'make config' are all cached to
     enhance performance and prevent duplicated	efforts.

     While recursing through the dependencies, if a port is marked IS_INTERAC-
     TIVE this will be flagged.	 In the	absence	of this	notification, under
     normal circumstances the only user	interaction required after the port
     starts building is	to answer questions about the deletion of stale	dist-
     files.  This can be eliminated with the -d	or -D options.

     There are a number	of --packages* options available to save the time that
     would normally be spent building the port(s).  Users interested in	a rea-
     sonable balance between speed of installation and maximum performance
     should consider the --packages-build option, perhaps combined with	the
     --delete-build-only option.

     If	there is no -B option specified	when updating an existing port,	a
     backup package will be created before pkg_delete(1) is called.  If	you
     are using the -b option, these packages can be found in a directory
     called "portmaster-backup"	in the directory specified by the PACKAGES
     environment variable, usually /usr/ports/packages.	 If there is no	-b
     option specified, the backup package will be deleted once the new version
     of	the port is successfully installed.  If	the installation fails for
     whatever reason, a	helpful	message	will be	printed, along with instruc-
     tions on where to find the	backup package.

     After the port is built, if the -w	option is being	used, all shared
     libraries installed by the	old port (if any) will be saved	to
     /usr/local/lib/compat/pkg.	 After installation if there are any new files
     with the same names as those in /usr/local/lib/compat/pkg the old files
     will be deleted, and ldconfig(8) will be run via /etc/rc.d/ldconfig.

     After the new port	is built, but before it	is installed the runtime
     dependencies will be checked to make sure they are	up to date.  If	the -g
     option is used a package will be created for the new (or newly installed)
     version.

     When installing a port or using the --check-depends option, if there are
     other ports that depend on	this port the dependent	ports +CONTENTS
     file(s), and the +REQUIRED_BY file	for the	new port will be updated.

     At	the conclusion of a successful installation, any pkg-message files
     that were installed, and a	summary	of the work performed will be dis-
     played.  If the --delete-build-only option	is in use, those packages that
     were installed during the current run of portmaster AND were only ever
     listed as build dependencies during this run will be deleted.

     If	something goes wrong during the	process	(e.g., a port build fails, a
     port is marked BROKEN) portmaster will report any work done successfully
     as	described above, then exit.

     The question is often asked, ``Why	is it not possible to proceed with the
     ports that	do not have errors?'' The answer is that (unfortunately)
     portmaster	is not omniscient, and cannot guess what resolution the	user
     would like	to have	for this problem.  Manual intervention is therefore
     required.

OPTIONS
     The options are as	follows:

     Common Flags:

     --force-config
	 run 'make config' for all ports (overrides -G)

     -C	 prevents 'make	clean' from being run before building

     -G	 prevents 'make	config'

     -H	 hide details of the port build	and install in a log file

     -K	 prevents 'make	clean' from being run after building

     -B	 prevents creation of the backup package for the installed port

     -b	 create	and keep a backup package of an	installed port

     -g	 create	a package of the new port

     -n	 run through all steps,	but do not make	or install any ports

     -t	 recurse dependencies thoroughly, using	all-depends-list.  RECOMMENDED
	 FOR USE ONLY WHEN NEEDED, NOT ROUTINELY. When applied to the
	 --clean-distfiles option it allows a distfile to be kept if it
	 matches any up	to date	port, not just the ones	that are installed.

     -v	 verbose output

     -w	 save old shared libraries before deinstall

     [-R] -f
	 always	rebuild	ports (overrides -i)

     -i	 interactive update mode -- ask	whether	to rebuild ports

     -D	 no cleaning of	distfiles

     -d	 always	clean distfiles

     -m	arguments for make
	 any arguments to supply to make(1)

     -x	 avoid building	or updating ports that match this pattern.  Can	be
	 specified more	than once.  If a port is not already installed the
	 exclude pattern will be run against the directory name	from
	 /usr/ports.

     --no-confirm
	 do not	ask the	user to	confirm	the list of ports to be	installed
	 and/or	updated	before proceeding

     --no-term-title
	 do not	update the xterm title bar

     --no-index-fetch
	 skip fetching the INDEX file

     --index
	 use INDEX-[7-9] exclusively to	check if a port	is up to date

     --index-first
	 use the INDEX for status, but double-check with the port

     --index-only
	 do not	try to use /usr/ports.	For updating ports when	no /usr/ports
	 directory is present the -PP|--packages-only option is	required.  See
	 the ENVIRONMENT section below for additional requirements.

     --delete-build-only
	 delete	ports that are build-only dependencies after a successful run,
	 only if installed this	run

     --update-if-newer
	 (only for multiple ports listed on the	command	line) do not
	 rebuild/reinstall if the installed version is up to date

     -P|--packages
	 use packages, but build port if not available

     -PP|--packages-only
	 fail if no package is available.  The -PP option must stand alone on
	 the command line.  In other words, you	cannot do -PPav	(for example).

     --packages-build
	 use packages for all build dependencies

     --packages-if-newer
	 use package if	newer than installed even if the package is not	the
	 latest	according to the ports tree

     --always-fetch
	 fetch package even if it already exists locally

     --local-packagedir=<path>
	 where local packages can be found, will fall back to fetching if no
	 local version exists.	This option should point to the	full path of a
	 directory structure created in	the same way that 'make	package' (or
	 the portmaster	-g option) creates it.	I.e., the package files	are
	 contained in <path>/All, there	are LATEST_LINK	symlinks in the
	 <path>/Latest directory, and symlinks to the packages in <path>/All
	 in the	category subdirectories, such as <path>/devel,
	 <path>/ports-mgmt, etc.

     --packages-local
	 use packages from --local-packagedir only

     --delete-packages
	 after installing from a package, delete it

     Features:

     -a	 check all ports, update as necessary

     --show-work
	 show what dependent ports are,	and are	not installed (implies -t).

     -o	<new port dir in /usr/ports> <installed	port>
	 replace the installed port with a port	from a different origin

     [-R] -r name/glob of port directory in /var/db/pkg
	 rebuild the specified port, and all ports that	depend on it.  The
	 list of dependent ports is built according to origin (i.e.,
	 category/portname) not	by the version number of the installed port.
	 So if you do portmaster -r fooport-1.23 and it	is necessary to
	 restart using -R but the newly	installed port is now fooport-1.24 you
	 can do	portmaster -R -r fooport-1.24 and it should pick up where you
	 left off.  The	-r option can be specified more	than once.

     -R	 used with the -r or -f	options	to skip	ports updated on a previous
	 run.  When used with -r it will also prevent the rebuild of the par-
	 ent port if it, and all of its	dependencies are up to date.

     -l	 list all installed ports by category

     -L	 list all installed ports by category, and search for updates

     --list-origins
	 list directories from /usr/ports for root and leaf ports.  This list
	 is suitable for feeding to portmaster either on another machine or
	 for reinstalling all ports.  See EXAMPLES below.

     [--force-config|-G] [-aftv] -F
	 fetch distfiles only

     -n	 answer	no to all user prompts for the features	below

     -y	 answer	yes to all user	prompts	for the	features below

     [-n|y] [-b] [-D|d]	-e name/glob of	a single port directory	in /var/db/pkg
	 expunge a port	using pkg_delete(1), and optionally remove all dist-
	 files.	 Calls -s after	it is done expunging in	case removing the port
	 causes	a dependency to	no longer be necessary.

     [-n|y] [-b] [-D|d]	-s
	 clean out stale ports that used to be depended	on

     [-t] [-n] --clean-distfiles
	 recurse through the installed ports to	get a list of distinfo files,
	 then recurse through all files	in /usr/ports/distfiles	to make	sure
	 that they are still associated	with an	installed port.	 If not, offer
	 to delete the stale file.  With the -t	option a distfile is consid-
	 ered valid if it is in	use by any port, not just those	installed.

     [-t]
	 -y --clean-distfiles does the same as above, but deletes all files
	 without prompting.

     [--index|--index-only] [-n] --clean-packages
	 offer to delete stale packages.  The --index-only option is required
	 if no ports tree is available.

     [--index|--index-only]
	 -y --clean-packages does the same as above, but deletes all out of
	 date files without prompting.

     [-n|y] [-v] --check-depends
	 cross-check and update	dependency information for all ports

     [-n|y] [-v] --check-port-dbdir
	 check for stale entries in /var/db/ports

     -h|--help
	 display help message

     --version
	 display the version number

ENVIRONMENT
     The directory pointed to by the PACKAGES variable (by default
     /usr/ports/packages) will be used to store	new and	backup packages.  When
     using 'make package' for the -g option, the ports infrastructure will
     store packages in ${PACKAGES}/All,	aka PKGREPOSITORY.  When using the -b
     option, portmaster	stores its backup packages in
     ${PACKAGES}/portmaster-backup so that you can create both a backup	pack-
     age and a package of the newly installed port even	if they	have the same
     version.

     When using	the --packages*	options	the package files will be downloaded
     to	${PACKAGES}/portmaster-download.  portmaster will respect the
     PACKAGESITE and PACKAGEROOT (by default http://ftp.freebsd.org) vari-
     ables.  portmaster	attempts to use	both of	these variables	in the same
     way that pkg_add(1) does.

     The UPGRADE_TOOL variable is set to "portmaster", and the UPGRADE_PORT
     and UPGRADE_PORT_VER variables are	set to the full	package	name string
     and version of the	existing package being replaced, if any.

     When using	the --index-only option	the PACKAGES variable must be set to a
     directory where the superuser has write permissions.  Other useful	vari-
     ables include:

     MASTER_SITE_INDEX	     (default http://www.FreeBSD.org/ports/)
     FETCHINDEX		     (default fetch -am	-o)
     INDEXDIR		     (default $PORTSDIR, or $TMPDIR for	--index-only)
     INDEXFILE		     (default auto per FreeBSD version)

     If	you use	non-standard OPTIONS settings for package building and wish to
     use the --index-only option without a ports tree you must generate	your
     own INDEX file so that the	dependencies match.

     If	you wish to customize your build environment on	a per-port basis you
     might want	to take	a look at /usr/ports/ports-mgmt/portconf

     To	log actions taken by portmaster	along with a date/time stamp you can
     define PM_LOG in your rc file with	the full path of the file you would
     like to log to.  If running portmaster with sudo(8) (see below) then you
     should make sure that the file is writable	by the unprivileged user.

     By	default	portmaster creates backup packages of installed	ports before
     it	runs pkg_delete(1) during an update.  If that package creation fails
     it	is treated as a	serious	error and the user is prompted.	 However for
     scripted use of portmaster	this can be a problem.	In situations where
     the user is ABSOLUTELY SURE that lack of a	backup package should not be a
     fatal error PM_IGNORE_FAILED_BACKUP_PACKAGE can be	defined	to any value
     in	the rc file.

     For those who wish	to be sure that	specific ports are always compiled
     instead of	being installed	from packages the PT_NO_INSTALL_PACKAGE	vari-
     able can be defined in the	make(1)	environment, perhaps in
     /usr/local/etc/ports.conf if using	/usr/ports/ports-mgmt/portconf,	or in
     /etc/make.conf.  This setting is not compatible with the
     -PP/--packages-only option.

FILES
     /usr/local/etc/portmaster.rc
     $HOME/.portmasterrc
	   Optional system and user configuration files.  The variables	set in
	   the script's	getopts	routine	can be specified in these files	to
	   enable those	options.  These	files will be read by the parent
	   portmaster process, and all variables in them will be exported.  If
	   a portmaster.rc file	is placed in the same directory	as the
	   portmaster script itself, it	will be	read as	described above.

     /var/db/pkg/*/+IGNOREME
	   If this file	exists for a port that is already installed, several
	   things will happen:

	   1. The port will be ignored for all purposes.
	       This includes dependency	updates	even if	there is no directory
	       for the port in /usr/ports and there is no entry	for it in
	       /usr/ports/MOVED.  If the -v option is used, the	fact that the
	       port is being ignored will be mentioned.

	   2. If using the
	       -L option, and a	new version exists, the	existence of the
	       +IGNOREME file will be mentioned.

	   3. If you do	a regular update of the	port, or if the
	       -a option is being used you will	be asked if you	want to	update
	       the port	anyway.

     /var/db/pkg/*/PM_UPGRADE_DONE_FLAG
	   Indicates to	a subsequent -a, -f, or	-r run which includes the -R
	   option that a port has already been rebuilt,	so it can be safely
	   ignored if it is up to date.

     /tmp/port_log-*
	   If the -H option is used, and the installation or upgrade is	not
	   successful, the results of the build	and install will be saved in
	   this	file.  Substitute the value of TMPDIR in your environment as
	   appropriate.

EXIT STATUS
     The portmaster utility exits 0 on success,	and >0 if an error occurs.

ADVANCED FEATURE: SU_CMD
     The ports infrastructure has limited support for performing various oper-
     ations as an unprivileged user.  It does this by defining SU_CMD, which
     is	typically su(1).  In order to support complete management of your
     ports as an unprivileged user, escalating to "root" privileges only when
     necessary,	portmaster can use sudo(1) to handle the escalated privileges.
     To	accomplish this	you must have the following directories	configured so
     that the unprivileged user	can access them:

     1.	WRKDIRPREFIX - This is usually set to /usr/ports/category/port/work,
	 however it is suggested that you configure another directory outside
	 your ports tree for access by the unprivileged	user, and assign this
	 variable to that value	in your	/etc/make.conf.

     2.	DISTDIR	- This is usually set to /usr/ports/distfiles.
	 This directory	can be safely set up for access	by the unprivileged
	 user, or a new	directory can be specified as above.

     3.	TMPDIR - Usually /tmp,
	 but can also be set to	another	directory in your shell	environment if
	 desired.

     It	is further assumed that	the following directories will be owned	by
     root:

     /var/db/pkg

     /var/db/ports

     LOCALBASE - Usually /usr/local

     PACKAGES -	Usually	/usr/ports/packages

     PKGREPOSITORY - Usually ${PACKAGES}/All

     You will then need	to install and configure sudo(1).  This	can easily be
     done with /usr/ports/security/sudo.  Then you will	need to	define
     PM_SU_CMD in your /etc/portmaster.rc file,	or your	$HOME/.portmasterrc
     file.  For	example:

	   PM_SU_CMD=/usr/local/bin/sudo

     You can optionally	define the PM_SU_VERBOSE option	as well	to notify you
     each time portmaster uses the PM_SU_CMD.  This is particularly useful if
     you are experimenting with	a tool other than sudo(1) to handle the	privi-
     lege escalation, although at this time sudo(1) is the only	supported
     option.

     PLEASE NOTE: You cannot upgrade the sudo(1) port itself using this
     method.

EXAMPLES
     The following are examples	of typical usage of the	portmaster command:

     Update one	port:
	   portmaster fooport-1.23 or
	   portmaster fooport or
	   portmaster foo/fooport

     Use a package if available:
	   portmaster --packages fooport-1.23

     Update multiple ports:
	   portmaster fooport-1.23 barport baz/blahport

     Build a port locally but use packages for build dependencies, then	delete
     the build dependencies when finished:
	   portmaster --packages-build --delete-build-only fooport-1.23

     Update a system using only	packages that are available locally:
	   portmaster -PP --local-packagedir=<path> -a

     Update all	ports that need	updating:
	   portmaster -a

     Update all	ports that need	updating, and delete stale distfiles after the
     update is done:
	   1. portmaster -aD
	   2. portmaster --clean-distfiles

     More complex tasks	(please	see the	details	for these options above):
	   portmaster -r fooport-1.23
	   portmaster -r fooport-1.23 -r barport-2.34
	   portmaster -o emulators/linux_base-fc4 linux_base-8-8.0_15
	   portmaster -a -x gstreamer -x linux

     Print only	the ports that have available updates.	This can be used as an
     alias in your shell.  Be sure to fix the line wrapping appropriately.
	   portmaster -L |
	   egrep -B1 '(ew|ort) version|Aborting|installed|dependencies|
	   IGNORE|marked|Reason:|MOVED|deleted|exist|update' | grep -v '^--'

     Using portmaster to do a complete reinstallation of all your ports:
	   1. portmaster --list-origins	> ~/installed-port-list
	   2. Update your ports	tree
	   3. portmaster -ty --clean-distfiles
	   4. portmaster --check-port-dbdir
	   5. portmaster -Faf
	   6. pkg_delete -a
	   7. rm -rf /usr/local/lib/compat/pkg
	   8. Back up any files	in /usr/local you wish to save,
	      such as configuration files in /usr/local/etc
	   9. Manually check /usr/local	and /var/db/pkg
	      to make sure that	they are really	empty
	   10. Re-install portmaster
	   11. portmaster `cat ~/installed-port-list`

     You probably want to use the -D option for	the installation and then run
     --clean-distfiles [-y] again when you are done.  You might	also want to
     consider using the	--force-config option when installing the new ports.

     Alternatively you could use portmaster -a -f -D to	do an ``in place''
     update of your ports.  If that process is interrupted for any reason you
     can use portmaster	-a -f -D -R to avoid rebuilding	ports already rebuilt
     on	previous runs.	However	the first method (delete everything and	rein-
     stall) is preferred.

SEE ALSO
     make(1), pkg_add(1), pkg_delete(1), su(1),	ports(7), ldconfig(8), sudo(8)

AUTHORS
     This manual page was written by Doug Barton <dougb@FreeBSD.org>.

FreeBSD	9.0		       December	12, 2011		   FreeBSD 9.0
Command Section