1 files changed, 152 insertions, 17 deletions

diff --git a/ports-mgmt/portmaster/files/portmaster.8 b/ports-mgmt/portmaster/files/portmaster.8
index f82090695b13..51890d881693 100644
--- a/ports-mgmt/portmaster/files/portmaster.8
+++ b/ports-mgmt/portmaster/files/portmaster.8
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd September 15, 2009
+.Dd December 1, 2009
 .Dt PORTMASTER 8
 .Os
 .Sh NAME
@@ -33,6 +33,11 @@
 .Sh SYNOPSIS
 Common Flags:
 .Op Fl -force-config CGHgntvw [B|b] [f|i] [D|d]
+.Op [--packages|--packages-only] [-P|-PP] | [--packages-build]
+.Op Fl -packages-if-newer
+.Op Fl -delete-build-only
+.Op Fl -always-fetch
+.Op Fl -local-packagedir=<path>
 .Op Fl m Ar arguments for make
 .Op Fl x Ar glob pattern to exclude from building
 .Nm
@@ -54,9 +59,6 @@ This is a change from pre-version-2.3 behavior.
 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
@@ -73,6 +75,23 @@ and/or multiple globs from /var/db/pkg
 .Op Common Flags
 .Fl a
 .Nm
+.Fl -delete-build-only
+.Nm
+.Op Fl -packages-if-newer
+.Op Fl -always-fetch
+.Op Fl -local-packagedir=<path>
+.Fl P|--packages
+.Nm
+.Op Fl -packages-if-newer
+.Op Fl -always-fetch
+.Op Fl -local-packagedir=<path>
+.Fl PP|--packages-only
+.Nm
+.Op Fl -packages-if-newer
+.Op Fl -always-fetch
+.Op Fl -local-packagedir=<path>
+.Fl -packages-build
+.Nm
 .Fl [l|L]
 .Nm
 .Op Fl b [D|d]
@@ -112,8 +131,8 @@ 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
+tracking information for your ports up to date.
+This allows you to update a specific port without
 having to update all of the ports
 .Qq above
 it.
@@ -139,6 +158,9 @@ option.
 It will then start building all ports that need
 updating.
 While recursing through dependencies,
+if you are not using any of the
+.Fl -packages*
+options,
 a 'make checksum' process will be launched
 in the background to either verify that the
 correct distfiles are available,
@@ -149,7 +171,7 @@ 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,
+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,
@@ -179,6 +201,17 @@ 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
+There are a number of
+.Fl -packages*
+options available to save the time that would normally
+be spent building the port(s).
+Users interested in a reasonable balance between speed of
+installation and maximum performance should consider the
+.Fl -packages-build
+option, perhaps combined with the
+.Fl -delete-build-only
+option.
+.Pp
 If there is no
 .Fl B
 option specified when updating an existing port,
@@ -220,7 +253,7 @@ 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
+option is used a package will be created for the new
 (or newly installed) version.
 .Pp
 When installing a port or using the
@@ -237,17 +270,25 @@ any
 .Pa pkg-message
 files that were installed,
 and a summary of the work performed will be displayed.
+If the
+.Fl -delete-build-only
+option is in use, those packages that were installed during
+the current run of
+.Nm
+AND were only ever listed as build dependencies during this
+run will be deleted.
 .Pp
 If something goes wrong during the process
 (e.g., a port build fails, a port is marked BROKEN)
 .Nm
 will report any work done successfully as described above,
 then exit.
+.Pp
 The question is often asked,
 .Dq Why is it not possible to proceed with the ports that do not have errors?
 The answer is that (unfortunately)
 .Nm
-is not omniscient, and therefore cannot guess what resolution the
+is not omniscient, and 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
@@ -259,7 +300,7 @@ option to the command line to skip the config phase the second time through.
 The options are as follows:
 .Bl -tag -width F1
 .It Fl -force-config
-run 'make config' for all ports (must be the first option)
+run 'make config' for all ports
 .It Fl B
 prevents creation of the backup package for the installed port
 .It Fl C
@@ -306,12 +347,14 @@ any arguments to supply to
 .It Fl 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
+.Pa /usr/ports .
 .It Fl p Ar port directory in /usr/ports
-specify the full path to a port directory
+This option has been deprecated.
 .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 <new port dir in /usr/ports> <installed port>
 replace the installed port with a port from a different origin
 .It [-R] Fl r Ar name/glob of port in /var/db/pkg
@@ -324,6 +367,44 @@ or
 options to skip ports updated on a previous run.
 .It Fl a
 check all ports, update as necessary
+.It Fl -delete-build-only
+delete ports that are build-only dependencies after a successful run,
+only if installed this run
+.It Fl P|--packages
+use packages, but build port if not available
+.It Fl PP|--packages-only
+fail if no package is available.
+The
+.Fl PP
+option must stand alone on the command line.
+In other words, you cannot do
+.Fl PPav
+(for example).
+.It Fl -packages-build
+use packages for all build dependencies
+.It Fl -packages-if-newer
+use package if newer than installed even if the package is not
+the latest according to the ports tree
+.It Fl -always-fetch
+fetch package even if it already exists locally
+.It Fl -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
+.Nm
+.Fl g
+option) creates it.
+I.e., the package files are contained in
+.Pa <path>/All ,
+there are LATEST_LINK symlinks in the
+.Pa <path>/Latest
+directory, and symlinks to the packages in
+.Pa <path>/All
+in the category subdirectories, such as
+.Pa <path>/devel ,
+.Pa <path>/ports-mgmt ,
+etc.
 .It Fl l
 list all installed ports by category
 .It Fl L
@@ -395,6 +476,22 @@ 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
+When using the
+.Fl -packages*
+options the package files will be downloaded to
+.Pa ${PACKAGES}/portmaster-download .
+.Nm
+will respect the
+.Ev PACKAGESITE
+and
+.Ev PACKAGEROOT
+(by default http://ftp.freebsd.org) variables.
+.Nm
+attempts to use both of these variables in the same
+way that
+.Xr pkg_add 1
+does.
+.Pp
 The
 .Ev UPGRADE_TOOL
 variable is set to
@@ -471,18 +568,44 @@ along with their related options.
 # RECURSE_THOROUGH=topt
 #
 # Be verbose (-v)
-# PM_VERBOSE=
+# 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
+# PM_BUILD_ONLY_LIST=pm_bol
+#
+# Delete build-only dependencies when finished (--delete-build-only)
+# PM_DEL_BUILD_ONLY=pm_dbo
+# PM_BUILD_ONLY_LIST=pm_bol
+#
+# 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>
 .Ed
 .Pp
 .It Pa /var/db/pkg/*/+IGNOREME
-If this file exists, several things will happen:
+If this file exists for a port that is already installed,
+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 ,
+.It 1. The port will be ignored for all purposes.
+This includes dependency updates even if there is no
+directory for the port in
+.Pa /usr/ports
 and there is no entry for it in
 .Pa /usr/ports/MOVED .
 If the
@@ -510,6 +633,7 @@ 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.
+.Pp
 .It Pa /tmp/port_log-*
 If the
 .Fl H
@@ -600,9 +724,19 @@ Update one port:
 .Dl "portmaster fooport"
 .Dl "portmaster foo/fooport"
 .Pp
+Use a package if available:
+.Dl "portmaster --packages fooport-1.23"
+.Pp
 Update multiple ports:
 .Dl "portmaster fooport-1.23 barport baz/blahport"
 .Pp
+Build a port locally but use packages for build dependencies,
+then delete the build dependencies when finished:
+.Dl "portmaster --packages-build --delete-build-only fooport-1.23"
+.Pp
+Update a system using only packages that are available locally:
+.Dl "portmaster -PP --local-packagedir=<path> -a"
+.Pp
 Update all ports that need updating:
 .Dl "portmaster -a"
 .Pp
@@ -654,6 +788,7 @@ to avoid rebuilding ports already rebuilt on previous runs.
 However the first method (delete everything and reinstall) is preferred.
 .Sh SEE ALSO
 .Xr make 1 ,
+.Xr pkg_add 1 ,
 .Xr pkg_delete 1 ,
 .Xr su 1 ,
 .Xr ports 7 ,