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

FreeBSD Manual Pages

  
 
  

home | help
PORTMASTER(8)		FreeBSD System Manager's Manual 	 PORTMASTER(8)

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

SYNOPSIS
     Common Flags: [--force-config -CGHgntvw -[B|b] -[f|i] -[D|d]]
     [-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] Multiple full names or paths from /usr/ports or
		/var/db/pkg, and/or multiple globs from /var/db/pkg
     portmaster [Common Flags] -p port directory in /usr/ports
     portmaster [Common Flags]
		 . (Use in /usr/ports/foo/bar to build that port)
     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
     portmaster [Common Flags] -a
     portmaster -[l|L]
     portmaster [-b -[D|d]] -e full name of port directory in /var/db/pkg
     portmaster [-b -[D|d]] -s
     portmaster --clean-distfiles
     portmaster --clean-distfiles-all
     portmaster --check-depends
     portmaster --check-port-dbdir
     portmaster --list-origins
     portmaster -h|--help
     portmaster --version

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, which allows you to update a spe-
     cific 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
     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.  It will then start building all ports that need
     updating.	While recursing through dependencies, a 'make checksum'
     process will be launched in the background to either verify that the cor-
     rect 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.

     If the recursion through the ports for 'make config' does not find a port
     that needs updating, the dependency check step will be skipped prior to
     building the port specified on the command 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 dupli-
     cated 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.

     While checking dependencies, if a port has CONFLICTS set, the list will
     be checked against your installed ports, and if you have installed an
     alternate version of a port that is required by the port you are build-
     ing, it will be used in place of the default dependency.

     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/compat/pkg.  After installation if there are any new files
     with the same names as those in /usr/local/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 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 there-
     fore cannot guess what resolution the user would like to have for this
     problem.  Manual intervention is therefore required.  Assuming that the
     failure occurred after the config phase has ended (i.e., something has
     started building), the user can save time by adding the -G option to the
     command line to skip the config phase the second time through.

OPTIONS
     The options are as follows:

     --force-config
	 run 'make config' for all ports (must be the first option)

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

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

     -G  prevents the recursive 'make config' (overrides --force-config)

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

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

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

     -g  create a package of the new port

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

     -t  recurse dependencies thoroughly, using all-depends-list

     -v  verbose output

     -w  save old shared libraries before deinstall

     -u  This option has been deprecated.  It did very little previously, and
	 not what most users expected.	Please check the -d and -D options to
	 achieve most of the same effect.

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

     -p port directory in /usr/ports
	 specify the full path to a port directory

     --show-work
	 show what dependent ports are, and are not installed (implies -t).
	 This flag must come first on the command line.

     -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 in /var/db/pkg
	 rebuild the specified port, and all ports that depend on it

     -R  used with the -r or -f options to skip ports updated on a previous
	 run.

     -a  check all ports, update as necessary

     -l  list all installed ports by category

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

     -e name of port directory in /var/db/pkg
	 expunge 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.

     -s  clean out stale ports that used to be depended on

     -F  fetch distfiles only.	Cannot be used with -G, but may be used with
	 --force-config and -[aftv].

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

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

     --check-depends
	 cross-check and update dependency information for all ports

     --check-port-dbdir
	 check for stale entries in /var/db/ports

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

     -h|--help
	 display help message

     --version
	 display the version only.

MAKE 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 /usr/ports/packages/All, aka PKGREPOSITORY.  When using
     the -b option, portmaster stores its backup packages in
     /usr/ports/packages/portmaster-backup so that you can create both a
     backup package and a package of the newly installed port even if they
     have the same version.

     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.

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.

	   PLEASE NOTE: In versions before 2.3 /etc/portmaster.rc was recom-
	   mended.  However placing this file in LOCALBASE is the correct
	   thing to do.  In future versions of portmaster support for
	   /etc/portmaster.rc will be removed.

	   Here are examples of variables that are likely to be useful, along
	   with their related options.

	   # Sample portmaster rc file.
	   # Place in $HOME/.portmasterrc or /usr/local/etc/portmaster.rc
	   #
	   # Do not create temporary backup packages before pkg_delete (-B)
	   # NO_BACKUP=Bopt
	   #
	   # Always save the backup packages of the old port (-b)
	   # BACKUP=bopt
	   #
	   # Make and save a package of the new port (-g)
	   # MAKE_PACKAGE=gopt
	   #
	   # Do not preclean the port's build directory (-C)
	   # DONT_PRE_CLEAN=Copt
	   #
	   # Do not clean the port's build directory after installation (-K)
	   # DONT_POST_CLEAN=Kopt
	   #
	   # Never search for stale distfiles to delete (-D)
	   # DONT_SCRUB_DISTFILES=Dopt
	   #
	   # Always delete stale distfiles without prompting (-d)
	   # ALWAYS_SCRUB_DISTFILES=dopt
	   #
	   # Do not run 'make config' for ports that need updating (-G)
	   # (This unsets --force-config)
	   # NO_RECURSIVE_CONFIG=Gopt
	   #
	   # Hide the build and install processes in a log file (-H)
	   # HIDE_BUILD=Hopt
	   #
	   # Arguments to pass to make (-m)
	   # PM_MAKE_ARGS='-DFORCE_PKG_REGISTER'
	   #
	   # Recurse through every dependency, and child dependencies (-t)
	   # RECURSE_THOROUGH=topt
	   #
	   # Be verbose (-v)
	   # PM_VERBOSE=
	   #
	   # Save copies of old shared libraries (recommended) (-w)
	   # SAVE_SHARED=wopt

     /var/db/pkg/*/+IGNOREME
	   If this file exists, several things will happen:

	   1. The port will be ignored for all purposes, including
	       dependency updates, if there is no directory for it 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 unpriviliged 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
	   portmaster fooport
	   portmaster foo/fooport

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

     Update all ports that need updating:
	   portmaster -a

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

     More complex tasks (please see the details for these options above):
	   portmaster -r fooport-1.23
	   portmaster -o emulators/linux_base-fc4 linux_base-8-8.0_15
	   portmaster -x cvsup -f -a
	   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' | 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 --clean-distfiles-all
	   4. portmaster --check-port-dbdir
	   5. portmaster -Faf
	   6. pkg_delete '*'
	   7. rm -rf /usr/local/lib/compat/pkg
	   8. Manually check /usr/local and /var/db/pkg
	      to make sure that they are really empty
	   9. portmaster `cat ~/installed-port-list`

     You probably want to use the -D option for the installation and then run
     --clean-distfiles[-all] 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_delete(1), su(1), ports(7), ldconfig(8), sudo(8)

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

FreeBSD 7.2		      September 15, 2009		   FreeBSD 7.2

NAME | SYNOPSIS | QUICK START GUIDE | DESCRIPTION | OPTIONS | MAKE ENVIRONMENT | FILES | EXIT STATUS | ADVANCED FEATURE: SU_CMD | EXAMPLES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=portmaster&manpath=FreeBSD+8.0-RELEASE+and+Ports>

home | help