Skip site navigation (1)Skip section navigation (2)
Date:      Thu, 14 Jun 2012 09:33:05 +0000
From:      scher@FreeBSD.org
To:        svn-soc-all@FreeBSD.org
Subject:   socsvn commit: r237676 - soc2012/scher/par_ports/head/Mk
Message-ID:  <20120614093305.0D926106564A@hub.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: scher
Date: Thu Jun 14 09:33:04 2012
New Revision: 237676
URL: http://svnweb.FreeBSD.org/socsvn/?view=rev&rev=237676

Log:
  [docs] Added docs for global variables. User variables have appropriate
  	assignments "?=". Changed docs for scripts.
  

Modified:
  soc2012/scher/par_ports/head/Mk/bsd.parallel.mk

Modified: soc2012/scher/par_ports/head/Mk/bsd.parallel.mk
==============================================================================
--- soc2012/scher/par_ports/head/Mk/bsd.parallel.mk	Thu Jun 14 07:51:37 2012	(r237675)
+++ soc2012/scher/par_ports/head/Mk/bsd.parallel.mk	Thu Jun 14 09:33:04 2012	(r237676)
@@ -5,17 +5,84 @@
 #
 # Please view me with 4 column tabs!
 
+# The following variables may be specified by user.
+# By the way, all this variable have default values.
 #
-# _parv_WANT_PARALLEL_BUILD
-# _parv_ATTEMPTS_TO_LOCK
+# _parv_WANT_PARALLEL_BUILD 	- trigger for parallel ports installation.
+#								  Set this variable to some value to enable
+#								  parallel ports build/install. It does not
+#								  matter what value is assigned.
+#								  Example: _parv_WANT_PARALLEL_BUILD=yes
+#
+# _parv_WAIT_FOR_LOCK_TIME 		- time in seconds to wait if lock file is locked
+#								  by lockf(1) in case of directory locking.
+#								  Default: 5
+#
+# _parv_WAIT_FOR_UNLOCK_TIME	- time in seconds to wait if lock file is locked
+#								  by lockf(1) in case of directory unlocking.
+#								  Default: 15
+#
+# _parv_LOCK_ATTEMPT_TIMEOUT	- while trying to lock a directory in "while"
+#								  loop, if the directory is locked, this
+#								  variable specifies delay in seconds before
+#								  next attempt to lock a directory. Default: 2
+#
+# _parv_ON_LOCK_FEEDBACK_TIMEOUT -while trying to lock a directory in "while"
+#								  loop, if the directory is locked, user
+#								  feedback is printed once in
+#                                 ${_parv_ON_LOCK_FEEDBACK_TIMEOUT} attempts.
+#								  Default: 2
+#
+# _parv_PARALLEL_BUILDS_NUMBER  - number of parallel dependency builds for
+#								  current port.
+#								  Default: ${_parv_DEFAULT_PAR_BUILDS_NUM} (see below).
+#								  If value of this variable is more then
+#								  ${_parv_DEFAULT_PAR_BUILDS_NUM}, then it will
+#								  be set to ${_parv_DEFAULT_PAR_BUILDS_NUM}.
+#
+# The following variables are not assumed to be changed by user
+#
+# _parv_ON_LOCK_EXIT_STATUS		- if the directory is locked script exits with
+#								  this exit status (2).
+#
+# _parv_MAKE_LOCK_EXIT_STATUS	- if port's directory is locked make(1) process
+#							      exits with this exit status (158).
+#
+# LOCK_DIR 						- directory that contains lock files of locked ports.
+#                                 Value: /var/db/portlocks
+#
+# _parv_PKG_DBDIR_LOCK_FILE		- name of lock file for ${PKG_DBDIR} locking.
+#								  Value: .lock
+#								  This file contains PID of the process, that
+#								  locked ${PKG_DBDIR}.
+#
+# _parv_LOCK_DIR_LOCK_FILE 		- name of lock file for ${LOCK_DIR} locking.
+#								  Value: ${PKGNAME}
+#								  This file contains PID of the process, that
+#								  locked ${LOCK_DIR}.
+#
+# _parv_DEFAULT_TARGETS			- sequence of bsd.port.mk targets. If at least
+#								  one of this targets is encounted in ${.TARGETS}
+#								  then port's directory has to be locked.
 #
+# _parv_DEFAULT_PAR_BUILDS_NUM 	- default number of parallel dependency builds.
+#								  Value: number of logical CPUs on user's machine.
 #
 
 .if !defined(_POSTMKINCLUDED) && !defined(Parallel_Pre_Include)
 Parallel_Pre_Include=	bsd.parallel.mk
 
-_dparv_=
-_parv_=
+#####################################################
+# Commands
+_parv_KILL= /bin/kill
+_parv_KILL_SIGNAL= USR1
+_parv_PKILL= /bin/pkill
+_parv_PKILL_FLAGS= -P
+_parv_UMASK= 777
+
+DO_NADA?=		${TRUE}
+# End of Commands section
+#####################################################
 #####################################################
 # Debugging specific tools and variable declarations
 _dparv_START_OUTPUT_MESSAGE= =================_PAR_PORTS_SPECIFIC_OUTPUT_==============
@@ -34,17 +101,14 @@
 breakpoint:
 	@${_dparv_DEBUGGING_BREAKPOINT}
 
-# Delay for feedback message if the directory is locked.
-# Just not to annoy a user with feedback message on each attempt to lock a directory.
-_parv_ON_LOCK_FEEDBACK_TIMEOUT?= 2
 # End of Debugging specific tools and variable declarations section 
 #####################################################
 #####################################################
 _parv_DEFAULT_TARGETS= all check-sanity fetch checksum extract patch configure build install
 _parv_IS_DEFAULT_TARGET= 0
 
-# e.g. make -D_parv_WANT_PARALLEL_BUILD
-# All target will be evaluated. It is in default sequence
+# in case of the following call: make -D_parv_WANT_PARALLEL_BUILD
+# "all" target will be evaluated. It is in default sequence, ${.TARGETS}="".
 #
 .if !${.TARGETS}
 _parv_IS_DEFAULT_TARGET= 1
@@ -69,52 +133,40 @@
 .endif
 #####################################################
 #####################################################
-# Commands
-_parv_KILL= /bin/kill
-_parv_KILL_SIGNAL= USR1
-_parv_PKILL= /bin/pkill
-_parv_PKILL_FLAGS= -P
-_parv_UMASK= 777
-
-DO_NADA?=		${TRUE}
-# End of Commands section
-#####################################################
-#####################################################
 # Locking variables and tools
-#PKG_DBDIR?=		/var/db/pkg
-LOCK_DIR?= /var/db/portlocks
+
+LOCK_DIR= /var/db/portlocks
 _parv_PKG_DBDIR_LOCK_FILE= .lock
 _parv_LOCK_DIR_LOCK_FILE= ${PKGNAME}
 
-_parv_WAIT_FOR_LOCK_TIME= 5
-_parv_WAIT_FOR_UNLOCK_TIME= 15
+_parv_WAIT_FOR_LOCK_TIME?= 5
+_parv_WAIT_FOR_UNLOCK_TIME?= 15
 
-# Delay in seconds between attempts to lock a directory in lock loops
-_parv_LOCK_ATTEMPT_TIMEOUT=2
+_parv_LOCK_ATTEMPT_TIMEOUT?= 2
+_parv_ON_LOCK_FEEDBACK_TIMEOUT?= 2
 
-# exit status of lock script in case the directory is locked
 _parv_ON_LOCK_EXIT_STATUS= 2
 _parv_LOCKF_EX_TEMPFAIL= 75
 
 _parv_MAKE_LOCK_EXIT_STATUS= 158
 
+.for _lock_dir in PKG_DBDIR LOCK_DIR
+# ${${_lock_dir}} == ${PKG_DBDIR} OR ${LOCK_DIR}
+
+# _parv_PKG_DBDIR_LOCK_SEQ
+# _parv_LOCK_DIR_LOCK_SEQ
+#
 # Senquence of commands to lock a directory using ${_parv_${_lock_dir}_LOCK_FILE}.
-# During evaluation of the following commands lockf(1) is holding lock on ${_parv_${_lock_dir}_LOCK_FILE} file.
-# Hence NO other process is able to evaluate any commands using lockf(1)
-# locking on the same ${_parv_${_lock_dir}_LOCK_FILE} file.
+# During evaluation of the following commands lockf(1) is holding lock on
+# ${_parv_${_lock_dir}_LOCK_FILE} file. Hence NO other process is able to evaluate
+# any commands using lockf(1) locking on the same ${_parv_${_lock_dir}_LOCK_FILE} file.
 # 
 # Stalled locks cheking enabled.
 #
 # If the directory is locked this script returns ${_parv_ON_LOCK_EXIT_STATUS}.
+# Process is allowed to work in locked port's directory if and only if it is locked
+# by it's parent process.
 #
-# ${${_lock_dir}} == ${PKG_DBDIR} OR ${LOCK_DIR}
-#
-.for _lock_dir in PKG_DBDIR LOCK_DIR
-# _parv_PKG_DBDIR_LOCK_SEQ
-# _parv_LOCK_DIR_LOCK_SEQ
-#
-#_parv_${_lock_dir}_LOCK_FILE:= ${_parv_${_lock_dir}_LOCK_FILE}
-
 _parv_${_lock_dir}_LOCK_SEQ= \
 	${CHMOD} ${_parv_UMASK} ${${_lock_dir}}/${_parv_${_lock_dir}_LOCK_FILE}; \
 	pid=$$(${CAT} ${${_lock_dir}}/${_parv_${_lock_dir}_LOCK_FILE}); \
@@ -160,7 +212,8 @@
 # _parv_PKG_DBDIR_DO_LOCK
 # _parv_LOCK_DIR_DO_LOCK
 # This scripts handles exit status of lockf(1) call.
-# It substitutes exit status 75 of lockf(1) for ${_parv_ON_LOCK_EXIT_STATUS} and pushes it.
+# It substitutes exit status 75 of lockf(1) for ${_parv_ON_LOCK_EXIT_STATUS}
+# and pushes it.
 #
 _parv_${_lock_dir}_DO_LOCK= \
 	lockf -k -t ${_parv_WAIT_FOR_LOCK_TIME} ${${_lock_dir}}/${_parv_${_lock_dir}_LOCK_FILE} ${SH} -c '${_parv_${_lock_dir}_LOCK_SEQ}' || { \
@@ -178,13 +231,17 @@
 
 #####################################################
 
-# Loops to lock directory
 # _parv_PKG_DBDIR_LOCK_LOOP
 # _parv_LOCK_DIR_LOCK_LOOP
-# $${attempts} - Number of attempts to lock a directory. Exetranl variable.
-# 				 Default value = 1, if this var is not set.
+# Loops to lock a directory
+# $${attempts} - Number of attempts to lock a directory. Exetranal variable.
+# 				 Default: 1, if this var is not set.
 #				 Set this variable to -1 for infinity loop.
-# e.g. ( attempts=10; ${_parv_LOCK_DIR_LOCK_LOOP} ) && ..... || ....
+# e.g. ( attempts=10; ${_parv_LOCK_DIR_LOCK_LOOP} ) && echo dir is locked \
+#													|| echo dir is not locked
+#
+# Script exits with ${_parv_ON_LOCK_EXIT_STATUS} status if it was unabled
+# to lock a directry after $${attempts} attempts.
 #
 _parv_${_lock_dir}_LOCK_LOOP= \
 	enable_feedback=${_parv_ON_LOCK_FEEDBACK_TIMEOUT}; \
@@ -233,16 +290,20 @@
 		fi; \
 	}'
 
-.endfor # _lock_dir in PKG_DBDIR .CURDIR
-.undef _parv_${_lock_dir}_LOCK_FILE
+#####################################################
+
+.endfor # .for _lock_dir in PKG_DBDIR LOCK_DIR
 #####################################################
 
 # _parv_CHECK_SEQ
 # _parv_CHECK_LOCK
-# The former variables Implement check for lock utility
-# $${pkg_name} - port to check. External variable for script. Supports shell RE. Assign this variable
-# appropriate value before executing this script e.g. ( pkg_name=apache-[1234]; ${_parv_CHECK_LOCK} ) || ...
-# Script exits with status ${_parv_ON_LOCK_EXIT_STATUS} if $${pkg_name} is locked
+# The former variables implement check for lock utility.
+# $${pkg_name}	 - port to check, since ${_parv_LOCK_DIR_LOCK_FILE} = ${PKGNAME}
+#				   External variable for script. Supports sh(1) patterns
+#				   (see Shell Patterns section). Assign this variable appropriate
+#				   value before executing this script.
+#				   e.g. ( pkg_name=apache-[1234]; ${_parv_CHECK_LOCK} ) || ...
+# Script exits with exit status ${_parv_ON_LOCK_EXIT_STATUS} if $${pkg_name} is locked
 # 
 _parv_CHECK_SEQ= \
 	${CHMOD} ${_parv_UMASK} ${LOCK_DIR}/$${pkg_name}; \



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20120614093305.0D926106564A>