Document bulk package building.

Stress important conditions that should be met for bugs to be avoided.

2 files changed, 73 insertions, 4 deletions

diff --git a/share/man/man5/bsd.port.mk.5 b/share/man/man5/bsd.port.mk.5
index f279c8da4f6..3a47ce3b2d0 100644
--- a/share/man/man5/bsd.port.mk.5
+++ b/share/man/man5/bsd.port.mk.5
@@ -1,4 +1,4 @@
-.\" $OpenBSD: bsd.port.mk.5,v 1.65 2002/04/02 16:03:47 espie Exp $
+.\" $OpenBSD: bsd.port.mk.5,v 1.66 2002/04/17 17:12:59 espie Exp $
 .\"
 .\" Copyright (c) 2000 Marc Espie
 .\"
@@ -86,10 +86,12 @@ main archive site.
 Clean ports contents. 
 By default, it will clean the work directory.
 It can be invoked as 
-make clean='[depends work fake flavors dist install sub package packages]'.
+make clean='[depends bulk work fake flavors dist install sub package packages]'.
 .Bl -tag -width packages
 .It Va work
 Clean work directory.
+.It Va bulk
+Clean bulk cookie.
 .It Va depends
 Recurse into dependencies.
 .It Va flavors
@@ -280,6 +282,16 @@ Defaults to ${WRKSRC}.
 .It Ev BSD_INSTALL_{PROGRAM,SCRIPT,DATA,MAN}[_DIR]
 Macros passed to make and configure invocations.
 Set based on corresponding INSTALL_* variables.
+.It Ev BIN_PACKAGES
+If set to
+.Sq Yes ,
+the 
+.Ar package
+target will trust a package built in the repository to be up-to-date,
+and will not rebuild it if the work directory is absent.
+See also
+.Ev BULK ,
+.Ev TRUST_PACKAGES .
 .It Ev BUILD_DEPENDS
 List of other ports the current port needs to build correctly.
 Each item has the form
@@ -302,6 +314,29 @@ package name.
 is a comma separated list of flavors.
 By default, the dependency will build the default flavor.
 Build dependencies are checked at the beginning of the extract stage.
+.It Ev BULK
+If set to 
+.Sq Yes ,
+succesful package builds and installations will clean
+their working directories, after invoking 
+.Ar ftp-packages ,
+.Ar cdrom-packages ,
+and any other targets mentioned in BULK_TARGETS.
+See
+.Ev BULK_COOKIES_DIR ,
+.Ev BIN_PACKAGES ,
+.Ev TRUST_PACKAGES .
+.It Ev BULK_COOKIES_DIR
+Used to store cookies for succesful bulk-package builds, defaults to
+.Pa ${PORTSDIR}/bulk/${MACHINE_ARCH} .
+.It Ev BULK_FLAGS
+Flags to pass to build each target in
+.Ev BULK_TARGETS .
+.It Ev BULK_TARGETS
+Targets to run after each bulk package build before cleaning up the 
+working directory. Defaults to
+.Ar ftp-packages ,
+.Ar cdrom-packages .
 .It Ev BZIP2
 Name of the bzip2 binary.
 .It Ev CATEGORIES
@@ -985,6 +1020,14 @@ Name of the tar binary.
 Base location for the templates used in the
 .Ar readme
 target.
+.It Ev TRUST_PACKAGES
+If set to
+.Sq Yes ,
+dependency mechanisms will assume the database of installed packages is
+correct.
+See also
+.Ev BIN_PACKAGES ,
+.Ev BULK .
 .It Ev UNZIP
 Name of the unzip binary.
 .It Ev WRKBUILD
@@ -1515,7 +1558,7 @@ Having a separate directory is enough to trick
 into grabbing the right version.
 Note that libraries used only for 
 .Xr dlopen 3
-do not need NEWDYNLIDIR.
+do not need NEWDYNLIBDIR.
 .Pp
 The special
 .Ar plist
diff --git a/share/man/man7/ports.7 b/share/man/man7/ports.7
index e77b51f09a0..6cd41a93d44 100644
--- a/share/man/man7/ports.7
+++ b/share/man/man7/ports.7
@@ -23,7 +23,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.\" $OpenBSD: ports.7,v 1.23 2002/04/04 20:54:08 espie Exp $
+.\" $OpenBSD: ports.7,v 1.24 2002/04/17 17:12:59 espie Exp $
 .\" $FreeBSD: ports.7,v 1.7 1998/06/23 04:38:50 hoek Exp $
 .\"
 .Dd January 25, 1998
@@ -261,6 +261,32 @@ belongs to.
 Remove the symbolic links created by
 .Ar link-categories .
 .El
+.Sh BULK PACKAGE BUILDING
+The ports tree contains some mechanisms to save space when building
+large collection of packages.
+If
+.Ev BIN_PACKAGES ,
+.Ev TRUST_PACKAGES ,
+and
+.Ev BULK
+are set to
+.Sq Yes 
+for a package build, some shortcuts are taken to allow cleaning up working
+directories on the fly.
+.Pp
+Some important caveats apply:
+the packages already built in the package repository are assumed to be 
+up-to-date (BIN_PACKAGES), the database of installed packages is assumed 
+to be accurate (TRUST_PACKAGES), and the bulk cookies are assumed to be 
+up-to-date (BULK).
+.Pp
+This means that newer iterations of package buildings should make sure
+those conditions are met, which entails erasing old package repository,
+removing packages that need to be rebuilt from the base of installed
+packages, and cleaning up old bulk cookies.
+.Pp
+If any of these conditions is not met, the package build may run into weird
+problems.
 .Sh NETWORK CONFIGURATION
 The variables pertaining to network access have been marshalled into
 .Pa ${PORTSDIR}/infrastructure/template/network.conf.template .