PORTMASTER(8) 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]] [[[--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] 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 --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 --delete-build-only portmaster [--packages-if-newer] [--always-fetch] [--local-packagedir=<path>] [--packages-local] [--delete-packages] -P|--packages portmaster [--packages-if-newer] [--always-fetch] [--local-packagedir=<path>] [--packages-local] [--delete-packages] -PP|--packages-only portmaster [--packages-if-newer] [--always-fetch] [--local-packagedir=<path>] [--packages-local] [--delete-packages] --packages-build portmaster -[l|L] portmaster [-b -[D|d]] -e name/glob 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 [-v] portmaster --list-origins portmaster -h|--help portmaster --version The "glob" patterns mentioned above are not regular expressions. For example: "portmaster perl" would match every port dirctory 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 updat- ing, 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 han- dle any port OPTIONS via the 'make config' interface. You will be pre- sented 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 version 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 pre- sented with a list of ports that will be installed and/or upgraded, and asked to approve before proceeding. This behavior can be supressed 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 command line. In addition to this optimization, information about up-to-date de- pendencies, choices made on which ports to build for interactive mode, and ports already visited for 'make config' are all cached to enhance perfor- mance 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 nor- mal circumstances the only user interaction required after the port starts building is to answer questions about the deletion of stale distfiles. 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 suc- cessfully installed. If the installation fails for whatever reason, a helpful message will be printed, along with instructions on where to find the backup package. After the port is built, if the -w option is being used, all shared li- braries 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 depen- dencies 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 displayed. If the --delete-build-only option is in use, those packages that were in- stalled 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 re- quired. OPTIONS The options are as follows: --force-config run 'make config' for all ports -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 spec- ified more than once. If a port is not already installed the exclude pattern will be run against the directory name from /usr/ports. -p port directory in /usr/ports This option has been deprecated. --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 -R used with the -r or -f options to skip ports updated on a previous run. -a check all ports, update as necessary --delete-build-only delete ports that are build-only dependencies after a successful run, only if installed this run -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 lat- est 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 lo- cal version exists. This option should point to the full path of a di- rectory structure created in the same way that 'make package' (or the portmaster -g option) creates it. I.e., the package files are con- tained 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 --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-[6-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. -l list all installed ports by category -L list all installed ports by category, and search for updates -e name/glob of port directory in /var/db/pkg expunge port using pkg_delete(1), and optionally remove all distfiles. 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 [-v] --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 re- installing all ports. See EXAMPLES below. -h|--help display help message --version display the version only. 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. 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) variables. 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 ver- sion of the existing package being replaced, if any. When using the --index-only option the PACKAGES and INDEXDIR variables must each be set to a dirctory where the superuser has write permissions. Other useful variables include: MASTER_SITE_INDEX (default http://www.FreeBSD.org/ports/) FETCHINDEX (default fetch -am -o) INDEXFILE (default auto per FreeBSD version) 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 en- able 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=vopt # # Save copies of old shared libraries (recommended) (-w) # SAVE_SHARED=wopt # # Install a package if available (-P or --packages) # PM_PACKAGES=first # # Only install packages (-PP or --packages-only) # PM_PACKAGES=only # # Install packages for build-only dependencies (--packages-build) # PM_PACKAGES_BUILD=pmp_build # # Delete build-only dependencies when finished (--delete-build-only) # PM_DEL_BUILD_ONLY=pm_dbo # # Use packages if they are newer than installed (--packages-newer) # PM_PACKAGES=newer # PM_PACKAGES_NEWER=pmp_newer # # Always fetch new package files (--always-fetch) # PM_ALWAYS_FETCH=pm_always_fetch # # Specify a local package repository (--local-packagedir) # LOCAL_PACKAGEDIR=<path> # # Only use packages from --local-packagedir (--packages-local) # PM_PACKAGES_LOCAL=pmp_local # # Delete packages after they are installed (--delete-packages) # PM_DELETE_PACKAGES=pm_delete_packages # # Suppress the build confirmation message (--no-confirm) # PM_NO_CONFIRM=pm_no_confirm # # Do not update the xterm title bar (--no-term-title) # PM_NO_TERM_TITLE=pm_no_term_title # # Do not fetch the INDEX file (--no-index-fetch) # PM_NO_INDEX_FETCH=pm_no_index_fetch # # Use only the INDEX file to check if a port is out of date (--index) # PM_INDEX=pm_index # # Use the INDEX file first, then check /usr/ports (--index-first) # PM_INDEX=pm_index # PM_INDEX_FIRST=pm_index_first # # Use the INDEX file instead of /usr/ports (--index-only) # PM_INDEX=pm_index # PM_INDEX_ONLY=pm_index_only /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 op- tion that a port has already been rebuilt, so it can be safely ig- nored if it is up to date. /tmp/port_log-* If the -H option is used, and the installation or upgrade is not suc- cessful, the results of the build and install will be saved in this file. Substitute the value of TMPDIR in your environment as appro- priate. 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 opera- tions 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 accom- plish 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 ex- ample: 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 op- tion. 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 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: 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. Re-install portmaster 10. 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 previ- ous runs. However the first method (delete everything and reinstall) 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 8.1 May 9, 2010 PORTMASTER(8)
NAME | SYNOPSIS | QUICK START GUIDE | DESCRIPTION | OPTIONS | ENVIRONMENT | FILES | EXIT STATUS | ADVANCED FEATURE: SU_CMD | EXAMPLES | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.FreeBSD.org/cgi/man.cgi?query=portmaster&sektion=8&manpath=FreeBSD+8.1-RELEASE+and+Ports>