Document locking infrastructure

ok naddy@

1 files changed, 44 insertions, 1 deletions

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.