.\" Copyright (c) 2006-2008 Doug Barton dougb@FreeBSD.org .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 28, 2008 .Dt PORTMASTER 8 .Os .Sh NAME .Nm portmaster .Nd manage your ports without external databases or languages .Sh SYNOPSIS Common Flags: .Op Fl -force-config CGHgntvw [B|b] [uf|i] [D|d] .Op Fl m Ar arguments for make .Op Fl x Ar glob pattern to exclude from building .Nm .Op Common Flags .Ar full name of port directory in /var/db/pkg .Nm .Op Common Flags .Ar full path to /usr/ports/foo/bar .Nm .Op Common Flags .Ar glob pattern of directories from /var/db/pkg .Pp PLEASE NOTE: Glob patterns now update every port that matches. This is a change from pre-version-2.3 behavior. .Pp .Nm .Op Common Flags .Ar Multiple full names or paths from /usr/ports or /var/db/pkg, and/or multiple globs from /var/db/pkg .Nm .Op Common Flags .Fl p Ar port directory in /usr/ports .Nm .Op Common Flags . (Use in /usr/ports/foo/bar to build that port) .Nm .Fl -show-work .Op Fl Gv m Ar args .Nm .Op Common Flags .Fl o Ar .Nm .Op Common Flags .Op Fl R .Fl r Ar name/glob of port in /var/db/pkg .Nm .Op Common Flags .Fl a .Nm .Fl [l|L] .Nm .Op Fl b [D|d] .Fl e Ar full name of port directory in .Pa /var/db/pkg .Nm .Op Fl b [D|d] .Fl s .Nm .Fl -clean-distfiles .Nm .Fl -clean-distfiles-all .Nm .Fl -check-depends .Nm .Fl h|--help .Nm .Fl -version .Pp .Sh DESCRIPTION The .Nm utility is a tool for updating your ports. It uses no external database to track what you have installed. Rather it uses the existing ports infrastructure, including what is located in .Pa /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 specific port without having to update all of the ports .Qq above it. In the rare case where you do need to recompile ports which depend on a port you are updating, the .Fl r option exists to accomplish this. .Pp By default .Nm 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 .Fl -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 correct distfiles are available, or start downloading the new ones. If you stop .Nm with ^C, an attempt will be made to kill off the child processes started for this purpose. .Pp 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 duplicated efforts. .Pp While recursing through the dependencies, if a port is marked IS_INTERACTIVE 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 distfiles. This can be eliminated with the .Fl d or .Fl D options. .Pp 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 building, it will be used in place of the default dependency. .Pp If there is no .Fl B option specified when updating an existing port, a backup package will be created before .Xr pkg_delete 1 is called. If you are using the .Fl b option, these packages can be found in a directory called .Qq portmaster-backup in the directory specified by the .Ev PACKAGES environment variable, usually .Pa /usr/ports/packages . If there is no .Fl 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 instructions on where to find the backup package. .Pp After the port is built, if the .Fl w option is being used, all shared libraries installed by the old port (if any) will be saved to .Pa /usr/local/compat/pkg . After installation if there are any new files with the same names as those in .Pa /usr/local/compat/pkg the old files will be deleted, and .Xr ldconfig 8 will be run via .Pa /etc/rc.d/ldconfig . .Pp 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 .Fl g option is used, a package will be created for the new (or newly installed) version. .Pp When installing a port or using the .Fl -check-depends option, if there are other ports that depend on this port the dependent ports .Pa +CONTENTS file(s), and the .Pa +REQUIRED_BY file for the new port will be updated. .Pp At the conclusion of a successful installation, any .Pa pkg-message files that were installed, and a summary of the work performed will be displayed. .Sh OPTIONS The options are as follows: .Bl -tag -width F1 .It Fl -force-config run 'make config' for all ports (must be the first option) .It Fl B prevents creation of the backup package for the installed port .It Fl C prevents 'make clean' from being run before building .It Fl G prevents the recursive 'make config' (overrides .Fl -force-config ) .It Fl H hide details of the port build and install in a log file .It Fl K prevents 'make clean' from being run after building .It Fl b create and keep a backup package of an installed port .It Fl g create a package of the new port .It Fl n run through configure, but do not make or install any ports .It Fl t recurse dependencies thoroughly, using all-depends-list .It Fl v verbose output .It Fl w save old shared libraries before deinstall .It Fl u unattended mode -- accept defaults for all but 'make config' .Pp PLEASE NOTE: Under most circumstances this option is not necessary, and may produce unwanted results. If you experience problems with .Nm , please try running it without this option first. .It [-R] Fl f always rebuild ports (overrides .Fl i ) .It Fl i interactive update mode -- ask whether to rebuild ports .It Fl D no cleaning of distfiles .It Fl d always clean distfiles .It Fl m Ar arguments for make any arguments to supply to .Xr make 1 .It Fl x avoid building or updating ports that match this pattern .It Fl p Ar port directory in /usr/ports specify the full path to a port directory .It Fl -show-work show what dependent ports are, and are not installed (implies .Fl t ) . This flag must come first on the command line. .It Fl o Ar replace the installed port with a port from a different origin .It [-R] Fl r Ar name/glob of port in /var/db/pkg rebuild the specified port, and all ports that depend on it .It Fl R restart an update, skipping ports already up to date. Used with .Fl r or .Fl f options. .It Fl a check all ports, update as necessary .It Fl l list all installed ports by category .It Fl L list all installed ports by category, and search for updates .It Fl e Ar name of port directory in /var/db/pkg expunge port using .Xr pkg_delete 1 , and optionally remove all distfiles. Calls .Fl s after it is done expunging in case removing the port causes a dependency to no longer be necessary. .It Fl s clean out stale ports that used to be depended on .It Fl F fetch distfiles only. Cannot be used with .Fl G , but may be used with .Fl -force-config and .Fl [aftv] . .It Fl -clean-distfiles recurse through the installed ports to get a list of distinfo files, then recurse through all files in .Pa /usr/ports/distfiles to make sure that they are still associated with an installed port. If not, offer to delete the stale file. .It Fl -clean-distfiles-all does the same as above, but deletes all files without prompting. .It Fl -check-depends cross-check and update dependency information for all ports .It Fl h|--help display help message .It Fl -version display the version only. .El .Sh MAKE ENVIRONMENT The directory pointed to by the .Ev PACKAGES variable (by default .Pa /usr/ports/packages ) will be used to store new and backup packages. When using 'make package' for the .Fl g option, the ports infrastructure will store packages in .Pa /usr/ports/packages/All , aka .Ev PKGREPOSITORY . When using the .Fl b option, .Nm stores its backup packages in .Pa /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. .Pp The .Ev UPGRADE_TOOL variable is set to .Qq Nm , and the .Ev UPGRADE_PORT and .Ev UPGRADE_PORT_VER variables are set to the full package name string and version of the existing package being replaced, if any. .Sh FILES .Bl -tag -width "1234" -compact .It Pa /usr/local/etc/portmaster.rc .It Pa $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 .Nm process, and all variables in them will be exported. .Pp PLEASE NOTE: In versions before 2.3 .Pa /etc/portmaster.rc was recommended. However placing this file in LOCALBASE is the correct thing to do. In future versions of .Nm support for .Pa /etc/portmaster.rc will be removed. .Pp Here are examples of variables that are likely to be useful, along with their related options. .Pp .Bd -literal # 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 .Ed .Pp .It Pa /var/db/pkg/*/+IGNOREME If this file exists, several things will happen: .Bl -tag -width F1 .It 1. The port will be ignored for all purposes, including dependency updates, if there is no directory for it in .Pa /usr/ports , and there is no entry for it in .Pa /usr/ports/MOVED . If the .Fl v option is used, the fact that the port is being ignored will be mentioned. .It 2. If using the .Fl L option, and a new version exists, the existence of the .Pa +IGNOREME file will be mentioned. .It 3. If you do a regular update of the port, or if the .Fl a option is being used, you will be asked if you want to update the port anyway; unless the .Fl u option is being used, in which case the port will be ignored. .El .Pp .It Pa /var/db/pkg/*/PM_UPGRADE_DONE_FLAG Indicates to a subsequent .Fl f or .Fl r run which includes the .Fl R option that a port has already been rebuilt, so it can be safely ignored if it is up to date. .It Pa /tmp/port_log-* If the .Fl 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 .Ev TMPDIR in your environment as appropriate. .El .Sh EXIT STATUS .Ex -std .Sh ADVANCED FEATURE: SU_CMD The ports infrastructure has limited support for performing various operations as an unpriviliged user. It does this by defining SU_CMD, which is typically .Xr su 1 . In order to support complete management of your ports as an unprivileged user, escalating to .Qq root privileges only when necessary, .Nm can use .Xr 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: .Bl -tag -width F1 .It 1. WRKDIRPREFIX - This is usually set to Pa /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 .Pa /etc/make.conf . .It 2. DISTDIR - This is usually set to Pa /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. .It 3. TMPDIR - Usually Pa /tmp , but can also be set to another directory in your shell environment if desired. .El .Pp It is further assumed that the following directories will be owned by root: .Bl -tag -width F1 .It Pa /var/db/pkg .It Pa /var/db/ports .It LOCALBASE - Usually Pa /usr/local .It PACKAGES - Usually Pa /usr/ports/packages .It PKGREPOSITORY - Usually Pa ${PACKAGES}/All .El .Pp You will then need to install and configure .Xr sudo 1 . This can easily be done with .Pa /usr/ports/security/sudo . Then you will need to define PM_SU_CMD in your .Pa /etc/portmaster.rc file, or your .Pa $HOME/.portmasterrc file. For example: .Pp .Dl "PM_SU_CMD=/usr/local/bin/sudo" .Pp You can optionally define the PM_SU_VERBOSE option as well to notify you each time .Nm uses the PM_SU_CMD. This is particularly useful if you are experimenting with a tool other than .Xr sudo 1 to handle the privilege escalation, although at this time .Xr sudo 1 is the only supported option. .Pp PLEASE NOTE: You cannot upgrade the .Xr sudo 1 port itself using this method. .Sh EXAMPLES The following are examples of typical usage of the .Nm command: .Pp .Dl "portmaster fooport-1.23" .Dl "portmaster fooport" .Dl "portmaster fooport-1.23 barport-4.56" .Dl "portmaster -p /usr/ports/foo/fooport" .Dl "portmaster foo/fooport" .Dl "portmaster -r fooport-1.23" .Dl "portmaster -o emulators/linux_base-fc4 linux_base-8-8.0_15" .Dl "portmaster -x cvsup -f -a" .Pp 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. .Dl "portmaster -L |" .Dl "egrep -B1 '(ew|ort) version|Aborting|installed|dependencies|" .Dl "IGNORE|marked|Reason:|MOVED' | grep -v '^--'" .Pp Using .Nm to do a complete reinstallation of all your ports: .Dl "1. portmaster -l > ~/installed-port-list" .Dl "2. Update your ports tree" .Dl "3. portmaster --clean-distfiles-all" .Dl "4. portmaster -Faf" .Dl "5. pkg_delete '*'" .Dl "6. rm -rf /usr/local/lib/compat/pkg" .Dl "7. Manually check through /usr/local to make sure it is really" .Dl " empty" .Pp .Dl "Now look at the list you generated in the first step and install" .Dl "all the root and leaf ports that you want to have again. The trunk" .Dl "and branch ports are dependencies, and will automatically be" .Dl "installed as needed. You probably want to use the -D option for" .Dl "the installations and then run --clean-distfiles-all again when" .Dl "you are done." .Sh SEE ALSO .Xr make 1 , .Xr pkg_delete 1 , .Xr su 1 , .Xr ports 7 , .Xr ldconfig 8 , .Xr sudo 8 .Sh AUTHORS This manual page was written by .An Doug Barton .