From owner-svn-soc-all@FreeBSD.ORG Thu Jun 14 09:33:07 2012 Return-Path: Delivered-To: svn-soc-all@FreeBSD.org Received: from socsvn.FreeBSD.org (unknown [IPv6:2001:4f8:fff6::2f]) by hub.freebsd.org (Postfix) with SMTP id 0D926106564A for ; Thu, 14 Jun 2012 09:33:05 +0000 (UTC) (envelope-from scher@FreeBSD.org) Received: by socsvn.FreeBSD.org (sSMTP sendmail emulation); Thu, 14 Jun 2012 09:33:05 +0000 Date: Thu, 14 Jun 2012 09:33:05 +0000 From: scher@FreeBSD.org To: svn-soc-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Message-Id: <20120614093305.0D926106564A@hub.freebsd.org> Cc: Subject: socsvn commit: r237676 - soc2012/scher/par_ports/head/Mk X-BeenThere: svn-soc-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for the entire Summer of Code repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 14 Jun 2012 09:33:07 -0000 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}; \