add eclass documentation by mren #210521

1 files changed, 108 insertions, 35 deletions

diff --git a/eclass/multilib.eclass b/eclass/multilib.eclass
index cce258db06f4..a048cc4b3e41 100644
--- a/eclass/multilib.eclass
+++ b/eclass/multilib.eclass
@@ -1,21 +1,18 @@
-# Copyright 1999-2007 Gentoo Foundation
+# Copyright 1999-2008 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
-# $Header: /var/cvsroot/gentoo-x86/eclass/multilib.eclass,v 1.64 2008/05/02 04:07:38 vapier Exp $
-#
-# Maintainer: amd64@gentoo.org / toolchain@gentoo.org
-#
-# This eclass is for all functions pertaining to handling multilib.
-# configurations.
+# $Header: /var/cvsroot/gentoo-x86/eclass/multilib.eclass,v 1.65 2008/06/01 01:37:29 vapier Exp $
+
+# @ECLASS: multilib.eclass
+# @MAINTAINER:
+# amd64@gentoo.org
+# toolchain@gentoo.org
+# @BLURB: This eclass is for all functions pertaining to handling multilib configurations.
+# @DESCRIPTION:
+# This eclass is for all functions pertaining to handling multilib configurations.
 
 ___ECLASS_RECUR_MULTILIB="yes"
 [[ -z ${___ECLASS_RECUR_TOOLCHAIN_FUNCS} ]] && inherit toolchain-funcs
 
-# has_multilib_profile:
-# Return true if the current profile is a multilib profile and lists more than
-# one abi in ${MULTILIB_ABIS}.  When has_multilib_profile returns true, that
-# profile should enable the 'multilib' use flag. This is so you can DEPEND on
-# a package only for multilib or not multilib.
-
 # is_final_abi:
 # Return true if ${ABI} is the final abi to be installed (and thus we are
 # on our last run through a src_* function.
@@ -105,19 +102,25 @@ export LIBDIR_default=${CONF_LIBDIR:-"lib"}
 export CDEFINE_default="__unix__"
 export KERNEL_ABI=${KERNEL_ABI:-${DEFAULT_ABI}}
 
-# has_multilib_profile()
+# @FUNCTION: has_multilib_profile
+# @DESCRIPTION:
+# Return true if the current profile is a multilib profile and lists more than
+# one abi in ${MULTILIB_ABIS}.  When has_multilib_profile returns true, that
+# profile should enable the 'multilib' use flag. This is so you can DEPEND on
+# a package only for multilib or not multilib.
 has_multilib_profile() {
 	[ -n "${MULTILIB_ABIS}" -a "${MULTILIB_ABIS}" != "${MULTILIB_ABIS/ /}" ]
 }
 
+# @FUNCTION: get_libdir
+# @RETURN: the libdir for the selected ABI
+# @DESCRIPTION:
 # This function simply returns the desired lib directory. With portage
 # 2.0.51, we now have support for installing libraries to lib32/lib64
 # to accomidate the needs of multilib systems. It's no longer a good idea
 # to assume all libraries will end up in lib. Replace any (sane) instances
 # where lib is named directly with $(get_libdir) if possible.
 #
-# Travis Tilley <lv@gentoo.org> (24 Aug 2004)
-#
 # Jeremy Huddleston <eradicator@gentoo.org> (23 Dec 2004):
 #   Added support for ${ABI} and ${DEFAULT_ABI}.  If they're both not set,
 #   fall back on old behavior.  Any profile that has these set should also
@@ -133,6 +136,8 @@ get_libdir() {
 	fi
 }
 
+# @FUNCTION: get_multilibdir
+# @RETURN: Returns the multilibdir
 get_multilibdir() {
 	if has_multilib_profile; then
 		eerror "get_multilibdir called, but it shouldn't be needed with the new multilib approach.  Please file a bug at http://bugs.gentoo.org and assign it to eradicator@gentoo.org"
@@ -141,6 +146,8 @@ get_multilibdir() {
 	echo ${CONF_MULTILIBDIR:=lib32}
 }
 
+# @FUNCTION: get_libdir_override
+# @DESCRIPTION:
 # Sometimes you need to override the value returned by get_libdir. A good
 # example of this is xorg-x11, where lib32 isnt a supported configuration,
 # and where lib64 -must- be used on amd64 (for applications that need lib
@@ -150,8 +157,6 @@ get_multilibdir() {
 # return:
 #
 #   get_libdir_override lib64
-#
-# Travis Tilley <lv@gentoo.org> (31 Aug 2004)
 get_libdir_override() {
 	if has_multilib_profile; then
 		eerror "get_libdir_override called, but it shouldn't be needed with the new multilib approach.  Please file a bug at http://bugs.gentoo.org and assign it to eradicator@gentoo.org"
@@ -162,9 +167,10 @@ get_libdir_override() {
 	LIBDIR_default="$1"
 }
 
-# get_abi_var <VAR> [<ABI>]
-# returns the value of ${<VAR>_<ABI>} which should be set in make.defaults
-#
+# @FUNCTION: get_abi_var
+# @USAGE: <VAR> [ABI]
+# @RETURN: returns the value of ${<VAR>_<ABI>} which should be set in make.defaults
+# @DESCRIPTION:
 # ex:
 # CFLAGS=$(get_abi_var CFLAGS sparc32) # CFLAGS=-m32
 #
@@ -174,8 +180,6 @@ get_libdir_override() {
 # If <ABI> is not specified, ${ABI} is used.
 # If <ABI> is not specified and ${ABI} is not defined, ${DEFAULT_ABI} is used.
 # If <ABI> is not specified and ${ABI} and ${DEFAULT_ABI} are not defined, we return an empty string.
-#
-# Jeremy Huddleston <eradicator@gentoo.org>
 get_abi_var() {
 	local flag=$1
 	local abi
@@ -193,15 +197,56 @@ get_abi_var() {
 	echo ${!var}
 }
 
+# @FUNCTION: get_abi_CFLAGS
+# @USAGE: [ABI]
+# @DESCRIPTION:
+# Alias for 'get_abi_var CFLAGS'
 get_abi_CFLAGS() { get_abi_var CFLAGS "$@"; }
+
+# @FUNCTION: get_abi_ASFLAGS
+# @USAGE: [ABI]
+# @DESCRIPTION:
+# Alias for 'get_abi_var ASFLAGS'
 get_abi_ASFLAGS() { get_abi_var ASFLAGS "$@"; }
+
+# @FUNCTION: get_abi_LDFLAGS
+# @USAGE: [ABI]
+# @DESCRIPTION:
+# Alias for 'get_abi_var LDFLAGS'
 get_abi_LDFLAGS() { get_abi_var LDFLAGS "$@"; }
+
+# @FUNCTION: get_abi_CHOST
+# @USAGE: [ABI]
+# @DESCRIPTION:
+# Alias for 'get_abi_var CHOST'
 get_abi_CHOST() { get_abi_var CHOST "$@"; }
+
+# @FUNCTION: get_abi_CTARGET
+# @USAGE: [ABI]
+# @DESCRIPTION:
+# Alias for 'get_abi_var CTARGET'
 get_abi_CTARGET() { get_abi_var CTARGET "$@"; }
+
+# @FUNCTION: get_abi_FAKE_TARGETS
+# @USAGE: [ABI]
+# @DESCRIPTION:
+# Alias for 'get_abi_var FAKE_TARGETS'
 get_abi_FAKE_TARGETS() { get_abi_var FAKE_TARGETS "$@"; }
+
+# @FUNCTION: get_abi_CDEFINE
+# @USAGE: [ABI]
+# @DESCRIPTION:
+# Alias for 'get_abi_var CDEFINE'
 get_abi_CDEFINE() { get_abi_var CDEFINE "$@"; }
+
+# @FUNCTION: get_abi_LIBDIR
+# @USAGE: [ABI]
+# @DESCRIPTION:
+# Alias for 'get_abi_var LIBDIR'
 get_abi_LIBDIR() { get_abi_var LIBDIR "$@"; }
 
+# @FUNCTION: get_install_abis
+# @DESCRIPTION:
 # Return a list of the ABIs we want to install for with
 # the last one in the list being the default.
 get_install_abis() {
@@ -241,6 +286,8 @@ get_install_abis() {
 	return 0
 }
 
+# @FUNCTION: get_all_abis
+# @DESCRIPTION: 
 # Return a list of the ABIs supported by this profile.
 # the last one in the list being the default.
 get_all_abis() {
@@ -262,9 +309,11 @@ get_all_abis() {
 	return 0
 }
 
-# get_all_libdirs()
+# @FUNCTION: get_all_libdirs
+# @DESCRIPTION:
 # Returns a list of all the libdirs used by this profile.  This includes
-# those that might not be touched by the current ebuild.
+# those that might not be touched by the current ebuild and always includes
+# "lib".
 get_all_libdirs() {
 	local libdirs="lib"
 	local abi
@@ -277,6 +326,8 @@ get_all_libdirs() {
 	echo "${libdirs}"
 }
 
+# @FUNCTION: is_final_abi
+# @DESCRIPTION:
 # Return true if ${ABI} is the last ABI on our list (or if we're not
 # using the new multilib configuration.  This can be used to determine
 # if we're in the last (or only) run through src_{unpack,compile,install}
@@ -287,14 +338,23 @@ is_final_abi() {
 	[[ ${LAST_ABI} == ${ABI} ]]
 }
 
+# @FUNCTION: number_abis
+# @DESCRIPTION:
 # echo the number of ABIs we will be installing for
 number_abis() {
 	get_install_abis | wc -w
 }
 
-# get_ml_incdir [<include dir> [<ABI>]]
+# @FUNCTION: get_ml_incdir
+# @USAGE: [include_dir] [ABI]
+# @DESCRIPTION:
 # include dir defaults to /usr/include
 # ABI defaults to ${ABI} or ${DEFAULT_ABI}
+#
+# If a multilib include dir is associated with the passed include dir, then
+# we return it, otherwise, we just echo back the include dir.  This is
+# neccessary when a built script greps header files rather than testing them
+# via #include (like perl) to figure out features.
 get_ml_incdir() {
 	local dir=/usr/include
 
@@ -321,8 +381,8 @@ get_ml_incdir() {
 	fi
 }
 
-# prep_ml_includes:
-#
+# @FUNCTION: prep_ml_includes
+# @DESCRIPTION:
 # Some includes (include/asm, glibc, etc) are ABI dependent.  In this case,
 # We can install them in different locations for each ABI and create a common
 # header which includes the right one based on CDEFINE_${ABI}.  If your
@@ -331,11 +391,10 @@ get_ml_incdir() {
 # files are installed in (default is /usr/include if none are passed).
 #
 # Example:
-# src_install() {
-#    ...
-#    prep_ml_includes /usr/qt/3/include
-# }
-
+#     src_install() {
+#        ...
+#        prep_ml_includes /usr/qt/3/include
+#     }
 prep_ml_includes() {
 	if [[ $(number_abis) -gt 1 ]] ; then
 		local dir
@@ -376,6 +435,9 @@ prep_ml_includes() {
 	fi
 }
 
+# @FUNCTION: create_ml_includes
+# @USAGE: <include_dir> <symbol_1>:<dir_1> [<symbol_2>:<dir_2>...]
+# @DESCRIPTION:
 # If you need more control than prep_ml_includes can offer (like linux-headers
 # for the asm-* dirs, then use create_ml_includes.  The firs argument is the
 # common dir.  The remaining args are of the form <symbol>:<dir> where
@@ -384,8 +446,8 @@ prep_ml_includes() {
 # Ideas for this code came from debian's sparc-linux headers package.
 #
 # Example:
-# create_ml_includes /usr/include/asm __sparc__:/usr/include/asm-sparc __sparc64__:/usr/include/asm-sparc64
-# create_ml_includes /usr/include/asm __i386__:/usr/include/asm-i386 __x86_64__:/usr/include/asm-x86_64
+#     create_ml_includes /usr/include/asm __sparc__:/usr/include/asm-sparc __sparc64__:/usr/include/asm-sparc64
+#     create_ml_includes /usr/include/asm __i386__:/usr/include/asm-i386 __x86_64__:/usr/include/asm-x86_64
 #
 # Warning: Be careful with the ordering here. The default ABI has to be the
 # last, because it is always defined (by GCC)
@@ -531,6 +593,15 @@ create_ml_includes-sym_for_dir() {
 	exit 1
 }
 
+# @FUNCTION: get_libname
+# @USAGE: [version]
+# @DESCRIPTION:
+# Returns libname with proper suffix {.so,.dylib} and optionally supplied version
+# for ELF/MACH-O shared objects
+#
+# Example:
+#     get_libname libfoo ${PV}
+#     Returns: libfoo.so.${PV} (ELF) || libfoo.${PV}.dylib (MACH)
 get_libname() {
 	local libname
 	local ver=$1
@@ -651,6 +722,8 @@ multilib_env() {
 	esac
 }
 
+# @FUNCTION: multilib_toolchain_setup
+# @DESCRIPTION:
 # Hide multilib details here for packages which are forced to be compiled for a
 # specific ABI when run on another ABI (like x86-specific packages on amd64)
 multilib_toolchain_setup() {