Document locking infrastructure

ok naddy@

2 files changed, 61 insertions, 2 deletions

diff --git a/share/man/man5/bsd.port.mk.5 b/share/man/man5/bsd.port.mk.5
index 422ee287ce5..02ed0b3ff33 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.143 2004/07/11 20:46:32 espie Exp $
+.\" $OpenBSD: bsd.port.mk.5,v 1.144 2004/07/20 05:44:34 espie Exp $
 .\"
 .\" Copyright (c) 2000 Marc Espie
 .\"
@@ -1010,6 +1010,17 @@ If USE_LIBTOOL is set, the environment variable LIBTOOL is set
 to ${LIBTOOL} ${LIBTOOL_FLAGS}.
 .It Ev LOCALBASE
 where other ports have already been installed (default: /usr/local)
+.It Ev LOCKDIR
+User settings.
+If set, points to a directory common for all instances of concurrent ports
+builds.
+.It Ev LOCK_CMD
+User settings.
+If set, expands to a command that will acquire a lock.
+This lock will reside in 
+.Pa ${LOCKDIR} .
+See also
+.Xr ports 7 .
 .It Ev LP64_ARCHS
 Set to the list of 64-bit architectures.
 Use with
@@ -1474,6 +1485,11 @@ correct.
 See also
 .Ev BIN_PACKAGES ,
 .Ev BULK .
+.It Ev UNLOCK_CMD
+User settings.
+If set, expands to a command that will release a lock.
+This lock will reside in 
+.Pa ${LOCKDIR} .
 .It Ev UNZIP
 Name of the unzip binary.
 .It Ev WARNINGS
diff --git a/share/man/man7/ports.7 b/share/man/man7/ports.7
index b44db824c72..b22f4fadbe3 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.42 2004/04/16 21:23:08 jmc Exp $
+.\" $OpenBSD: ports.7,v 1.43 2004/07/20 05:44:35 espie Exp $
 .\" $FreeBSD: ports.7,v 1.7 1998/06/23 04:38:50 hoek Exp $
 .\"
 .Dd January 25, 1998
@@ -271,6 +271,49 @@ belongs to.
 Remove the symbolic links created by
 .Ar link-categories .
 .El
+.Sh LOCK INFRASTRUCTURE
+The ports tree can be used concurrently for building several ports at the
+same time, thanks to a locking mechanism.
+By default, this mechanism is disabled.
+Defining 
+.Ev LOCKDIR ,
+.Ev LOCK_CMD ,
+and
+.Ev UNLOCK_CMD
+to proper values will activate it.
+.Pp
+All locks will be stored in
+.Pa ${LOCKDIR} .
+.Ev LOCK_CMD 
+should be used to acquire a lock, and
+.Ev UNLOCK_CMD should be used to release it.
+.Pp
+Locks are named ${LOCKDIR}/${FULLPKGNAME}.lock, 
+or ${LOCKDIR}/${DISTFILE}.lock for distfiles fetching.
+.Pp
+The locking protocol follows a big-lock model: each top-level target
+in a port directory will acquire the corresponding lock, complete its job, 
+then release the lock, e.g., running 
+.Bd -literal -offset indent
+$ make build 
+.Ed
+.Pp
+will acquire the lock, run the port
+through 
+.Ar fetch ,
+.Ar checksum ,
+.Ar extract ,
+.Ar patch ,
+.Ar configure ,
+.Ar build ,
+then release the lock.
+If dependencies are involved, they will invoke top-level targets in other
+directories, and thus acquire some other locks as well.
+.Pp
+At no moment should a given invocation of 
+.Xr make 1
+acquire the same lock twice, thus recursive locking is not needed for 
+.Ev LOCK_CMD .
 .Sh BULK PACKAGE BUILDING
 The ports tree contains some mechanisms to save space when building
 large collections of packages.