move man page documentation to eclass

1 files changed, 196 insertions, 167 deletions

diff --git a/eclass/eutils.eclass b/eclass/eutils.eclass
index 1098937b16c1..8b4379adeb4f 100644
--- a/eclass/eutils.eclass
+++ b/eclass/eutils.eclass
@@ -1,31 +1,42 @@
 # Copyright 1999-2007 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
-# $Header: /var/cvsroot/gentoo-x86/eclass/eutils.eclass,v 1.282 2007/06/16 07:11:43 vapier Exp $
-#
-# This eclass is for general purpose functions that most ebuilds
-# have to implement themselves.
-#
-# NB:  If you add anything, please comment it!
-#
-# Maintainer: see each individual function, base-system@gentoo.org as default
+# $Header: /var/cvsroot/gentoo-x86/eclass/eutils.eclass,v 1.283 2007/06/16 08:03:28 vapier Exp $
+
+# @ECLASS: eutils.eclass
+# @MAINTAINER:
+# base-system@gentoo.org
+# @BLURB: many extra (but common) functions that are used in ebuilds
+# @DESCRIPTION:
+# The eutils eclass contains a suite of functions that complement
+# the ones that ebuild.sh already contain.  The idea is that the functions
+# are not required in all ebuilds but enough utilize them to have a common
+# home rather than having multiple ebuilds implementing the same thing.
+# 
+# Due to the nature of this eclass, some functions may have maintainers
+# different from the overall eclass!
 
 inherit multilib portability
 
 DESCRIPTION="Based on the ${ECLASS} eclass"
 
-# Wait for the supplied number of seconds. If no argument is supplied, defaults
-# to five seconds. If the EPAUSE_IGNORE env var is set, don't wait. If we're not
-# outputting to a terminal, don't wait. For compatability purposes, the argument
-# must be an integer greater than zero.
-# Bug 62950, Ciaran McCreesh <ciaranm@gentoo.org> (05 Sep 2004)
+# @FUNCTION: epause
+# @USAGE: [seconds]
+# @DESCRIPTION:
+# Sleep for the specified number of seconds (default of 5 seconds).  Useful when
+# printing a message the user should probably be reading and often used in
+# conjunction with the ebeep function.  If the EPAUSE_IGNORE env var is set,
+# don't wait at all.
 epause() {
 	[[ -z ${EPAUSE_IGNORE} ]] && sleep ${1:-5}
 }
 
-# Beep the specified number of times (defaults to five). If our output
-# is not a terminal, don't beep. If the EBEEP_IGNORE env var is set,
-# don't beep.
-# Bug 62950, Ciaran McCreesh <ciaranm@gentoo.org> (05 Sep 2004)
+# @FUNCTION: ebeep
+# @USAGE: [number of beeps]
+# @DESCRIPTION:
+# Issue the specified number of beeps (default of 5 beeps).  Useful when
+# printing a message the user should probably be reading and often used in
+# conjunction with the epause function.  If the EBEEP_IGNORE env var is set,
+# don't beep at all.
 ebeep() {
 	local n
 	if [[ -z ${EBEEP_IGNORE} ]] ; then
@@ -304,11 +315,11 @@ epatch() {
 	fi
 }
 
+# @FUNCTION: emktemp
+# @USAGE: [temp dir]
+# @DESCRIPTION:
 # Cheap replacement for when debianutils (and thus mktemp)
-# does not exist on the users system
-# vapier@gentoo.org
-#
-# Takes just 1 optional parameter (the directory to create tmpfile in)
+# does not exist on the users system.
 emktemp() {
 	local exe="touch"
 	[[ $1 == -d ]] && exe="mkdir" && shift
@@ -339,12 +350,16 @@ emktemp() {
 	fi
 }
 
+# @FUNCTION: egetent
+# @USAGE: <database> <key>
+# @MAINTAINER:
+# base-system@gentoo.org (Linux)
+# Joe Jezak <josejx@gmail.com> (OS X)
+# usata@gentoo.org (OS X)
+# Aaron Walker <ka0ttic@gentoo.org> (FreeBSD)
+# @DESCRIPTION:
 # Small wrapper for getent (Linux), nidump (Mac OS X),
 # and pw (FreeBSD) used in enewuser()/enewgroup()
-# Joe Jezak <josejx@gmail.com> and usata@gentoo.org
-# FBSD stuff: Aaron Walker <ka0ttic@gentoo.org>
-#
-# egetent(database, key)
 egetent() {
 	case ${CHOST} in
 	*-darwin*)
@@ -378,19 +393,14 @@ egetent() {
 	esac
 }
 
-# Simplify/standardize adding users to the system
-# vapier@gentoo.org
-#
-# enewuser(username, uid, shell, homedir, groups, extra options)
-#
-# Default values if you do not specify any:
-# username:	REQUIRED !
-# uid:		next available (see useradd(8))
-#		note: pass -1 to get default behavior
-# shell:	/bin/false
-# homedir:	/dev/null
-# groups:	none
-# extra:	comment of 'added by portage for ${PN}'
+# @FUNCTION: enewuser
+# @USAGE: <user> [uid] [shell] [homedir] [groups] [params]
+# @DESCRIPTION:
+# Same as enewgroup, you are not required to understand how to properly add
+# a user to the system.  The only required parameter is the username.
+# Default uid is (pass -1 for this) next available, default shell is
+# /bin/false, default homedir is /dev/null, there are no default groups,
+# and default params sets the comment as 'added by portage for ${PN}'.
 enewuser() {
 	case ${EBUILD_PHASE} in
 		unpack|compile|test|install)
@@ -589,15 +599,13 @@ enewuser() {
 	export SANDBOX_ON=${oldsandbox}
 }
 
-# Simplify/standardize adding groups to the system
-# vapier@gentoo.org
-#
-# enewgroup(group, gid)
-#
-# Default values if you do not specify any:
-# groupname:	REQUIRED !
-# gid:		next available (see groupadd(8))
-# extra:	none
+# @FUNCTION: enewgroup
+# @USAGE: <group> [gid]
+# @DESCRIPTION:
+# This function does not require you to understand how to properly add a
+# group to the system.  Just give it a group name to add and enewgroup will
+# do the rest.  You may specify the gid for the group or allow the group to
+# allocate the next available one.
 enewgroup() {
 	case ${EBUILD_PHASE} in
 		unpack|compile|test|install)
@@ -703,21 +711,17 @@ enewgroup() {
 	export SANDBOX_ON="${oldsandbox}"
 }
 
-# Simple script to replace 'dos2unix' binaries
-# vapier@gentoo.org
-#
-# edos2unix(file, <more files> ...)
+# @FUNCTION: edos2unix
+# @USAGE: <file> [more files ...]
+# @DESCRIPTION:
+# A handy replacement for dos2unix, recode, fixdos, etc...  This allows you
+# to remove all of these text utilities from DEPEND variables because this
+# is a script based solution.  Just give it a list of files to convert and
+# they will all be changed from the DOS CRLF format to the UNIX LF format.
 edos2unix() {
 	echo "$@" | xargs sed -i 's/\r$//'
 }
 
-
-##############################################################
-# START: Handle .desktop files and menu entries				 #
-# maybe this should be separated into a new eclass some time #
-# lanius@gentoo.org											 #
-##############################################################
-
 # Make a desktop file !
 # Great for making those icons in kde/gnome startmenu !
 # Amaze your friends !	Get the women !	 Join today !
@@ -870,12 +874,12 @@ make_desktop_entry() {
 	)
 }
 
-
-# Validate desktop entries using desktop-file-utils
+# @FUNCTION: validate_desktop_entries
+# @USAGE: [directories]
+# @MAINTAINER:
 # Carsten Lohrke <carlo@gentoo.org>
-#
-# Usage: validate_desktop_entries [directory ...]
-
+# @DESCRIPTION:
+# Validate desktop entries using desktop-file-utils
 validate_desktop_entries() {
 	if [[ -x /usr/bin/desktop-file-validate ]] ; then
 		einfo "Checking desktop entry validity"
@@ -898,13 +902,11 @@ validate_desktop_entries() {
 	fi
 }
 
-
-# Make a GDM/KDM Session file
-#
-# make_session_desktop(<title>, <command>)
-# title: File to execute to start the Window Manager
-# command: Name of the Window Manager
-
+# @FUNCTION: make_session_desktop
+# @USAGE: <title> <command>
+# @DESCRIPTION:
+# Make a GDM/KDM Session file.  The title is the file to execute to start the
+# Window Manager.  The command is the name of the Window Manager.
 make_session_desktop() {
 	[[ -z $1 ]] && eerror "make_session_desktop: You must specify the title" && return 1
 	[[ -z $2 ]] && eerror "make_session_desktop: You must specify the command" && return 1
@@ -931,6 +933,11 @@ make_session_desktop() {
 	)
 }
 
+# @FUNCTION: domenu
+# @USAGE: <menus>
+# @DESCRIPTION:
+# Install the list of .desktop menu files into the appropriate directory
+# (/usr/share/applications).
 domenu() {
 	(
 	# wrap the env here so that the 'insinto' call
@@ -951,6 +958,11 @@ domenu() {
 	exit ${ret}
 	)
 }
+
+# @FUNCTION: newmenu
+# @USAGE: <menu> <newname>
+# @DESCRIPTION:
+# Like all other new* functions, install the specified menu as newname.
 newmenu() {
 	(
 	# wrap the env here so that the 'insinto' call
@@ -960,6 +972,11 @@ newmenu() {
 	)
 }
 
+# @FUNCTION: doicon
+# @USAGE: <list of icons>
+# @DESCRIPTION:
+# Install the list of icons into the icon directory (/usr/share/pixmaps).
+# This is useful in conjunction with creating desktop/menu files.
 doicon() {
 	(
 	# wrap the env here so that the 'insinto' call
@@ -980,6 +997,11 @@ doicon() {
 	exit ${ret}
 	)
 }
+
+# @FUNCTION: newicon
+# @USAGE: <icon> <newname>
+# @DESCRIPTION:
+# Like all other new* functions, install the specified icon as newname.
 newicon() {
 	(
 	# wrap the env here so that the 'insinto' call
@@ -989,11 +1011,6 @@ newicon() {
 	)
 }
 
-##############################################################
-# END: Handle .desktop files and menu entries			   #
-##############################################################
-
-
 # for internal use only (unpack_pdv and unpack_makeself)
 find_unpackable_file() {
 	local src=$1
@@ -1012,26 +1029,30 @@ find_unpackable_file() {
 	echo "${src}"
 }
 
+# @FUNCTION: unpack_pdv
+# @USAGE: <file to unpack> <size of off_t>
+# @DESCRIPTION:
 # Unpack those pesky pdv generated files ...
 # They're self-unpacking programs with the binary package stuffed in
 # the middle of the archive.  Valve seems to use it a lot ... too bad
 # it seems to like to segfault a lot :(.  So lets take it apart ourselves.
+# 
+# You have to specify the off_t size ... I have no idea how to extract that
+# information out of the binary executable myself.  Basically you pass in
+# the size of the off_t type (in bytes) on the machine that built the pdv
+# archive.
 #
-# Usage: unpack_pdv [file to unpack] [size of off_t]
-# - you have to specify the off_t size ... i have no idea how to extract that
-#	information out of the binary executable myself.  basically you pass in
-#	the size of the off_t type (in bytes) on the machine that built the pdv
-#	archive.  one way to determine this is by running the following commands:
+# One way to determine this is by running the following commands:
 #	strings <pdv archive> | grep lseek
 #	strace -elseek <pdv archive>
-#	basically look for the first lseek command (we do the strings/grep because
-#	sometimes the function call is _llseek or something) and steal the 2nd
-#	parameter.	here is an example:
-#	root@vapier 0 pdv_unpack # strings hldsupdatetool.bin | grep lseek
+# Basically look for the first lseek command (we do the strings/grep because
+# sometimes the function call is _llseek or something) and steal the 2nd
+# parameter.  Here is an example:
+#	vapier@vapier 0 pdv_unpack # strings hldsupdatetool.bin | grep lseek
 #	lseek
-#	root@vapier 0 pdv_unpack # strace -elseek ./hldsupdatetool.bin
+#	vapier@vapier 0 pdv_unpack # strace -elseek ./hldsupdatetool.bin
 #	lseek(3, -4, SEEK_END)					= 2981250
-#	thus we would pass in the value of '4' as the second parameter.
+# Thus we would pass in the value of '4' as the second parameter.
 unpack_pdv() {
 	local src=$(find_unpackable_file "$1")
 	local sizeoff_t=$2
@@ -1103,15 +1124,17 @@ unpack_pdv() {
 	#assert "failure unpacking pdv ('${metaskip}' '${tailskip}' '${datafile}')"
 }
 
+# @FUNCTION: unpack_makeself
+# @USAGE: [file to unpack] [offset] [tail|dd]
+# @DESCRIPTION:
 # Unpack those pesky makeself generated files ...
 # They're shell scripts with the binary package tagged onto
 # the end of the archive.  Loki utilized the format as does
 # many other game companies.
-#
-# Usage: unpack_makeself [file to unpack] [offset] [tail|dd]
-# - If the file is not specified then unpack will utilize ${A}.
-# - If the offset is not specified then we will attempt to extract
-#	the proper offset from the script itself.
+# 
+# If the file is not specified, then ${A} is used.  If the
+# offset is not specified then we will attempt to extract
+# the proper offset from the script itself.
 unpack_makeself() {
 	local src_input=${1:-${A}}
 	local src=$(find_unpackable_file "${src_input}")
@@ -1191,10 +1214,11 @@ unpack_makeself() {
 	assert "failure unpacking (${filetype}) makeself ${shrtsrc} ('${ver}' +${skip})"
 }
 
-# Display a license for user to accept.
-#
-# Usage: check_license [license]
-# - If the file is not specified then ${LICENSE} is used.
+# @FUNCTION: check_license
+# @USAGE: [license]
+# @DESCRIPTION:
+# Display a license for user to accept.  If no license is
+# specified, then ${LICENSE} is used.
 check_license() {
 	local lic=$1
 	if [ -z "${lic}" ] ; then
@@ -1250,28 +1274,28 @@ check_license() {
 	esac
 }
 
+# @FUNCTION: cdrom_get_cds
+# @USAGE: <file on cd1> [file on cd2] [file on cd3] [...]
+# @DESCRIPTION:
 # Aquire cd(s) for those lovely cd-based emerges.  Yes, this violates
 # the whole 'non-interactive' policy, but damnit I want CD support !
-#
-# with these cdrom functions we handle all the user interaction and
-# standardize everything.  all you have to do is call cdrom_get_cds()
+# 
+# With these cdrom functions we handle all the user interaction and
+# standardize everything.  All you have to do is call cdrom_get_cds()
 # and when the function returns, you can assume that the cd has been
 # found at CDROM_ROOT.
-#
-# normally the cdrom functions will refer to the cds as 'cd #1', 'cd #2',
-# etc...  if you want to give the cds better names, then just export
+# 
+# The function will attempt to locate a cd based upon a file that is on
+# the cd.  The more files you give this function, the more cds
+# the cdrom functions will handle.
+# 
+# Normally the cdrom functions will refer to the cds as 'cd #1', 'cd #2',
+# etc...  If you want to give the cds better names, then just export
 # the appropriate CDROM_NAME variable before calling cdrom_get_cds().
-#  - CDROM_NAME="fooie cd"	   - for when you only want 1 cd
-#  - CDROM_NAME_1="install cd" - for when you want more than 1 cd
-#	 CDROM_NAME_2="data cd"
-#  - CDROM_NAME_SET=( "install cd" "data cd" ) - short hand for CDROM_NAME_#
-#
-# for those multi cd ebuilds, see the cdrom_load_next_cd() below.
-#
-# Usage: cdrom_get_cds <file on cd1> [file on cd2] [file on cd3] [...]
-# - this will attempt to locate a cd based upon a file that is on
-#	the cd ... the more files you give this function, the more cds
-#	the cdrom functions will handle
+# Use CDROM_NAME for one cd, or CDROM_NAME_# for multiple cds.  You can
+# also use the CDROM_NAME_SET bash array.
+# 
+# For those multi cd ebuilds, see the cdrom_load_next_cd() function.
 cdrom_get_cds() {
 	# first we figure out how many cds we're dealing with by
 	# the # of files they gave us
@@ -1367,10 +1391,14 @@ cdrom_get_cds() {
 	cdrom_load_next_cd
 }
 
-# this is only used when you need access to more than one cd.
-# when you have finished using the first cd, just call this function.
-# when it returns, CDROM_ROOT will be pointing to the second cd.
-# remember, you can only go forward in the cd chain, you can't go back.
+# @FUNCTION: cdrom_load_next_cd
+# @DESCRIPTION:
+# Some packages are so big they come on multiple CDs.  When you're done reading
+# files off a CD and want access to the next one, just call this function.
+# Again, all the messy details of user interaction are taken care of for you.
+# Once this returns, just read the variable CDROM_ROOT for the location of the
+# mounted CD.  Note that you can only go forward in the CD list, so make sure
+# you only call this function when you're done using the current CD.
 cdrom_load_next_cd() {
 	local var
 	((++CDROM_CURRENT_CD))
@@ -1506,13 +1534,9 @@ strip-linguas() {
 	export LINGUAS=${newls:1}
 }
 
-# moved from kernel.eclass since they are generally useful outside of
-# kernel.eclass -iggy (20041002)
-
-# the following functions are useful in kernel module ebuilds, etc.
-# for an example see ivtv or drbd ebuilds
-
-# set's ARCH to match what the kernel expects
+# @FUNCTION: set_arch_to_kernel
+# @DESCRIPTION:
+# Set the env ARCH to match what the kernel expects.
 set_arch_to_kernel() {
 	i=10
 	while ((i--)) ; do
@@ -1529,7 +1553,9 @@ set_arch_to_kernel() {
 	esac
 }
 
-# set's ARCH back to what portage expects
+# @FUNCTION: set_arch_to_portage
+# @DESCRIPTION:
+# Set the env ARCH to match what portage expects.
 set_arch_to_portage() {
 	i=10
 	while ((i--)) ; do
@@ -1538,28 +1564,15 @@ set_arch_to_portage() {
 	export ARCH="${EUTILS_ECLASS_PORTAGE_ARCH}"
 }
 
-# Jeremy Huddleston <eradicator@gentoo.org>:
-# preserve_old_lib /path/to/libblah.so.0
-# preserve_old_lib_notify /path/to/libblah.so.0
-#
-# These functions are useful when a lib in your package changes --library.	Such
-# an example might be from libogg.so.0 to libogg.so.1.	Removing libogg.so.0
+# @FUNCTION: preserve_old_lib
+# @USAGE: <libs to preserve> [more libs]
+# @DESCRIPTION:
+# These functions are useful when a lib in your package changes ABI SONAME.
+# An example might be from libogg.so.0 to libogg.so.1.  Removing libogg.so.0
 # would break packages that link against it.  Most people get around this
 # by using the portage SLOT mechanism, but that is not always a relevant
-# solution, so instead you can add the following to your ebuilds:
-#
-# pkg_preinst() {
-# ...
-# preserve_old_lib /usr/$(get_libdir)/libogg.so.0
-# ...
-# }
-#
-# pkg_postinst() {
-# ...
-# preserve_old_lib_notify /usr/$(get_libdir)/libogg.so.0
-# ...
-# }
-
+# solution, so instead you can call this from pkg_preinst.  See also the
+# preserve_old_lib_notify function.
 preserve_old_lib() {
 	if [[ ${EBUILD_PHASE} != "preinst" ]] ; then
 		eerror "preserve_old_lib() must be called from pkg_preinst() only"
@@ -1577,6 +1590,10 @@ preserve_old_lib() {
 	done
 }
 
+# @FUNCTION: preserve_old_lib_notify
+# @USAGE: <libs to notify> [more libs]
+# @DESCRIPTION:
+# Spit helpful messages about the libraries preserved by preserve_old_lib.
 preserve_old_lib_notify() {
 	if [[ ${EBUILD_PHASE} != "postinst" ]] ; then
 		eerror "preserve_old_lib_notify() must be called from pkg_postinst() only"
@@ -1599,17 +1616,24 @@ preserve_old_lib_notify() {
 	done
 }
 
-# Hack for people to figure out if a package was built with
-# certain USE flags
-#
-# Usage: built_with_use [--missing <action>] [-a|-o] <DEPEND ATOM> <List of USE flags>
-#	 ex: built_with_use xchat gtk2
-#
-# Flags: -a         all USE flags should be utilized
-#        -o         at least one USE flag should be utilized
-#        --missing  peform the specified action if the flag is not in IUSE (true/false/die)
-#        --hidden   USE flag we're checking is hidden expanded so it isnt in IUSE
-# Note: the default flag is '-a'
+# @FUNCTION: built_with_use
+# @USAGE: [--hidden] [--missing <action>] [-a|-o] <DEPEND ATOM> <List of USE flags>
+# @DESCRIPTION:
+# A temporary hack until portage properly supports DEPENDing on USE
+# flags being enabled in packages.  This will check to see if the specified
+# DEPEND atom was built with the specified list of USE flags.  The
+# --missing option controls the behavior if called on a package that does
+# not actually support the defined USE flags (aka listed in IUSE).
+# The default is to abort (call die).  The -a and -o flags control
+# the requirements of the USE flags.  They correspond to "and" and "or"
+# logic.  So the -a flag means all listed USE flags must be enabled
+# while the -o flag means at least one of the listed fIUSE flags must be
+# enabled.  The --hidden option is really for internal use only as it
+# means the USE flag we're checking is hidden expanded, so it won't be found
+# in IUSE like normal USE flags.
+# 
+# Remember that this function isn't terribly intelligent so order of optional
+# flags matter.
 built_with_use() {
 	local hidden="no"
 	if [[ $1 == "--hidden" ]] ; then
@@ -1680,8 +1704,13 @@ built_with_use() {
 	[[ ${opt} = "-a" ]]
 }
 
-# Many configure scripts wrongly bail when a C++ compiler
-# could not be detected. #73450
+# @DESCRIPTION: epunt_cxx
+# @USAGE: [dir to scan]
+# @DESCRIPTION:
+# Many configure scripts wrongly bail when a C++ compiler could not be
+# detected.  If dir is not specified, then it defaults to ${S}.
+#
+# http://bugs.gentoo.org/73450
 epunt_cxx() {
 	local dir=$1
 	[[ -z ${dir} ]] && dir=${S}
@@ -1693,15 +1722,13 @@ epunt_cxx() {
 	eend 0
 }
 
-# make a wrapper script ...
-# NOTE: this was originally games_make_wrapper, but I noticed other places where
-# this could be used, so I have moved it here and made it not games-specific
-# -- wolf31o2
-# $1 == wrapper name
-# $2 == binary to run
-# $3 == directory to chdir before running binary
-# $4 == extra LD_LIBRARY_PATH's (make it : delimited)
-# $5 == path for wrapper
+# @FUNCTION: make_wrapper
+# @USAGE: <wrapper> <target> <chdir> [libpaths] [installpath]
+# @DESCRIPTION:
+# Create a shell wrapper script named wrapper in installpath
+# (defaults to the bindir) to execute target (default of wrapper) by
+# first optionally setting LD_LIBRARY_PATH to the colon-delimited
+# libpaths followed by optionally changing directory to chdir.
 make_wrapper() {
 	local wrapper=$1 bin=$2 chdir=$3 libdir=$4 path=$5
 	local tmpwrapper=$(emktemp)
@@ -1721,9 +1748,11 @@ exec ${bin} "\$@"
 EOF
 	chmod go+rx "${tmpwrapper}"
 	if [[ -n ${path} ]] ; then
+		(
 		exeinto "${path}"
 		newexe "${tmpwrapper}" "${wrapper}"
+		) || die
 	else
-		newbin "${tmpwrapper}" "${wrapper}"
+		newbin "${tmpwrapper}" "${wrapper}" || die
 	fi
 }