[binutil.inc] added commentaries for the functions searching for the dynamic dependencies of binaries

1 files changed, 63 insertions, 17 deletions

diff --git a/helper/binutil.inc b/helper/binutil.inc
index 261ccf16..72a43ad2 100644
--- a/helper/binutil.inc
+++ b/helper/binutil.inc
@@ -3,24 +3,45 @@
 # Common functions to copy binaries and their dependancies.
 #
 ############################################################
+#	This will parse the output of ldd on given binaries
+#	and echo the location of these libs to STDOUT
+#	The output of this function has to be used in some
+#	way, it only echos!	
 #
-# Usage: get_dynamic_dependencies [-l <searchdir>] <binary_list>
-# 	  * the list must be seperated by spaces
-#	  * the search for lib needed by a binary can be done locally,
-#	    using the -l <searchdir> option
+# About local search:
+#	It is required that we can search for the dynamic
+#	libraries in a specific directory, namely the one
+#	where we (potentially) built the binary. If a 
+#	corresponding library is found, it should take 
+#	precedence over ones found on the system.
+#	This can be done by using the '-l' switch, see below.
 #
-# Ouput: 
-#	 Will simply echo list of required libraries
-
-# List of libraries to exclude from
+############################################################
+# We use a blacklist mechanism to exclude common libraries.
+# This improve runtime quite a bit...
 BLACKLIST="ld-linux linux-gate linux-vdso libc.so"
+
+# Initialise flag and path for local search
 LOCALSEARCH=0
 LOCALSEARCHDIR=""
 
+# replace ' ' by '|' in the blacklist, so grep can use it directly.
 CURRENT_BLACKLIST=$(echo ${BLACKLIST} | sed 's/ /\\|/g')
 
+############################################################
+#
+# Usage: 
+#	get_dynamic_dependencies [-l <searchdir>] <binary_list>
+# 	  * the list must be seperated by spaces
+#	  * the search for lib needed by a binary can be done locally,
+#	    using the -l <searchdir> option
+#
+# Ouput: 
+#	 Will simply echo list of required libraries
+
 get_dynamic_dependencies() {
-	
+	# check if local search is activated by the '-l' switch
+	# if so the following argument is the path.
 	if [ "x$1" == "x-l" ]; then
 		LOCALSEARCH=1
 		shift
@@ -29,22 +50,25 @@ get_dynamic_dependencies() {
 		shift
 	fi	
 
+	# main loop over the list of binaries
 	while [ $# != 0 ]; do
 		local BINARY=$1
 		shift
 
+		# now run ldd on it and save the output in $LDD_OUT
 		local LDD_OUT="ldd_output"
 		if ldd $BINARY > $LDD_OUT; then
-			# Case 1: dynamic
+			# Case 1: file is a dynamic executable
 			for LIB in $(cat $LDD_OUT | grep -v "${CURRENT_BLACKLIST}" | awk '{print $1 $2 $3}'); do
 				# split the entry into an array, ex:
 				# libm.so.6 => /lib/libm.so.6 would be split into:
 				# LIBLINK[0]   LIBLINK[1]
 				local LIBLINK=(${LIB//=>/ })
+				# call helper function to find the correct lib
 				lib_search
 			done
 		else
-			# Case 2: not a dynamic
+			# Case 2: not a dynamic, do nothing
 			pdebug "\t\t\t(Not a dynamic.)"
 			rm -f $LDD_OUT
 			continue
@@ -54,6 +78,20 @@ get_dynamic_dependencies() {
 
 }
 
+############################################################
+#
+# Usage:
+#	lib_search
+#
+# Output:
+#	List of the path including any possible symbolic links
+#	of the found libraries.
+#
+# Note: This function takes no argument. It takes the library
+#	to look for from the local array LIBLINK.
+#	If the local was activated in get_dynamic_dependencies
+#	this will search for the library in LOCALSEARCHDIR first.
+#	If its not found, then it will look system-wide.
 lib_search(){
 
 	# if activated, start by searching the lib locally
@@ -85,13 +123,14 @@ lib_search(){
 }
 ############################################################
 #
-# Usage: get_link_chain <link> [prefix] 
-#
-#	<link> must be in absolute form-
-#	[prefix] is the prefix to strip from the ouput.
+# Usage:
+#	get_link_chain <link> [prefix] 
+#	  * <link> must be in absolute form-
+#	  * [prefix] is the prefix to strip from the ouput.
 #
 # Output:
 #	 Lists the symlink chain until a hardlink is found.
+#
 get_link_chain() {
 
 	# sanity checks
@@ -156,8 +195,15 @@ get_link_chain() {
 	done
 	pdebug "\t\t$CHAIN"
 }
-
-# Function to get libc and ld-linux
+############################################################
+#
+# Usage:
+#	list_basic_libs
+#
+# Output:
+#	list the path of following basic system libraries:
+#	- libc.so, ld-linux.so
+#
 list_basic_libs() {
         for i in $(ldd ${SHELL})
         do